Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test::Tutorial.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test::Tutorial 3pm"
61 .TH Test::Tutorial 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test::Tutorial \- A tutorial about writing really basic tests
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 \&\fIAHHHHHHH!!!! NOT TESTING! Anything but testing!
71 Beat me, whip me, send me to Detroit, but don\*(Aqt make
72 me write tests!\fR
73 .PP
74 \&\fI*sob*\fR
75 .PP
76 \&\fIBesides, I don\*(Aqt know how to write the damned things.\fR
77 .PP
78 Is this you? Is writing tests right up there with writing
79 documentation and having your fingernails pulled out? Did you open up
80 a test and read
81 .PP
82 .Vb 1
83 \& ######## We start with some black magic
84 .Ve
85 .PP
86 and decide that\*(Aqs quite enough for you?
87 .PP
88 It\*(Aqs ok. That\*(Aqs all gone now. We\*(Aqve done all the black magic for
89 you. And here are the tricks...
90 .SS "Nuts and bolts of testing."
91 .IX Subsection "Nuts and bolts of testing."
92 Here\*(Aqs the most basic test program.
93 .PP
94 .Vb 1
95 \& #!/usr/bin/perl \-w
96 \&
97 \& print "1..1\en";
98 \&
99 \& print 1 + 1 == 2 ? "ok 1\en" : "not ok 1\en";
100 .Ve
101 .PP
102 Because 1 + 1 is 2, it prints:
103 .PP
104 .Vb 2
105 \& 1..1
106 \& ok 1
107 .Ve
108 .PP
109 What this says is: \f(CW1..1\fR "I\*(Aqm going to run one test." [1] \f(CW\*(C`ok 1\*(C'\fR
110 "The first test passed". And that\*(Aqs about all magic there is to
111 testing. Your basic unit of testing is the \fIok\fR. For each thing you
112 test, an \f(CW\*(C`ok\*(C'\fR is printed. Simple. Test::Harness interprets your test
113 results to determine if you succeeded or failed (more on that later).
114 .PP
115 Writing all these print statements rapidly gets tedious. Fortunately,
116 there\*(Aqs Test::Simple. It has one function, \f(CWok()\fR.
117 .PP
118 .Vb 1
119 \& #!/usr/bin/perl \-w
120 \&
121 \& use Test::Simple tests => 1;
122 \&
123 \& ok( 1 + 1 == 2 );
124 .Ve
125 .PP
126 That does the same thing as the previous code. \f(CWok()\fR is the backbone
127 of Perl testing, and we\*(Aqll be using it instead of roll\-your\-own from
128 here on. If \f(CWok()\fR gets a true value, the test passes. False, it
129 fails.
130 .PP
131 .Vb 1
132 \& #!/usr/bin/perl \-w
133 \&
134 \& use Test::Simple tests => 2;
135 \& ok( 1 + 1 == 2 );
136 \& ok( 2 + 2 == 5 );
137 .Ve
138 .PP
139 From that comes:
140 .PP
141 .Vb 5
142 \& 1..2
143 \& ok 1
144 \& not ok 2
145 \& # Failed test (test.pl at line 5)
146 \& # Looks like you failed 1 tests of 2.
147 .Ve
148 .PP
149 \&\f(CW1..2\fR "I\*(Aqm going to run two tests." This number is a \fIplan\fR. It helps to
150 ensure your test program ran all the way through and didn\*(Aqt die or skip some
151 tests. \f(CW\*(C`ok 1\*(C'\fR "The first test passed." \f(CW\*(C`not ok 2\*(C'\fR "The second test failed".
152 Test::Simple helpfully prints out some extra commentary about your tests.
153 .PP
154 It\*(Aqs not scary. Come, hold my hand. We\*(Aqre going to give an example
155 of testing a module. For our example, we\*(Aqll be testing a date
156 library, Date::ICal. It\*(Aqs on CPAN, so download a copy and follow
157 along. [2]
158 .SS "Where to start?"
159 .IX Subsection "Where to start?"
160 This is the hardest part of testing, where do you start? People often get
161 overwhelmed at the apparent enormity of the task of testing a whole module.
162 The best place to start is at the beginning. Date::ICal is an
163 object\-oriented module, and that means you start by making an object. Test
164 \&\f(CWnew()\fR.
165 .PP
166 .Vb 1
167 \& #!/usr/bin/perl \-w
168 \&
169 \& # assume these two lines are in all subsequent examples
170 \& use strict;
171 \& use warnings;
172 \&
173 \& use Test::Simple tests => 2;
174 \&
175 \& use Date::ICal;
176 \&
177 \& my $ical = Date::ICal\->new; # create an object
178 \& ok( defined $ical ); # check that we got something
179 \& ok( $ical\->isa(\*(AqDate::ICal\*(Aq) ); # and it\*(Aqs the right class
180 .Ve
181 .PP
182 Run that and you should get:
183 .PP
184 .Vb 3
185 \& 1..2
186 \& ok 1
187 \& ok 2
188 .Ve
189 .PP
190 Congratulations! You\*(Aqve written your first useful test.
191 .SS Names
192 .IX Subsection "Names"
193 That output isn\*(Aqt terribly descriptive, is it? When you have two tests you can
194 figure out which one is #2, but what if you have 102 tests?
195 .PP
196 Each test can be given a little descriptive name as the second
197 argument to \f(CWok()\fR.
198 .PP
199 .Vb 1
200 \& use Test::Simple tests => 2;
201 \&
202 \& ok( defined $ical, \*(Aqnew() returned something\*(Aq );
203 \& ok( $ical\->isa(\*(AqDate::ICal\*(Aq), " and it\*(Aqs the right class" );
204 .Ve
205 .PP
206 Now you\*(Aqll see:
207 .PP
208 .Vb 3
209 \& 1..2
210 \& ok 1 \- new() returned something
211 \& ok 2 \- and it\*(Aqs the right class
212 .Ve
213 .SS "Test the manual"
214 .IX Subsection "Test the manual"
215 The simplest way to build up a decent testing suite is to just test what
216 the manual says it does. [3] Let\*(Aqs pull something out of the
217 "SYNOPSIS" in Date::ICal and test that all its bits work.
218 .PP
219 .Vb 1
220 \& #!/usr/bin/perl \-w
221 \&
222 \& use Test::Simple tests => 8;
223 \&
224 \& use Date::ICal;
225 \&
226 \& $ical = Date::ICal\->new( year => 1964, month => 10, day => 16,
227 \& hour => 16, min => 12, sec => 47,
228 \& tz => \*(Aq0530\*(Aq );
229 \&
230 \& ok( defined $ical, \*(Aqnew() returned something\*(Aq );
231 \& ok( $ical\->isa(\*(AqDate::ICal\*(Aq), " and it\*(Aqs the right class" );
232 \& ok( $ical\->sec == 47, \*(Aq sec()\*(Aq );
233 \& ok( $ical\->min == 12, \*(Aq min()\*(Aq );
234 \& ok( $ical\->hour == 16, \*(Aq hour()\*(Aq );
235 \& ok( $ical\->day == 17, \*(Aq day()\*(Aq );
236 \& ok( $ical\->month == 10, \*(Aq month()\*(Aq );
237 \& ok( $ical\->year == 1964, \*(Aq year()\*(Aq );
238 .Ve
239 .PP
240 Run that and you get:
241 .PP
242 .Vb 11
243 \& 1..8
244 \& ok 1 \- new() returned something
245 \& ok 2 \- and it\*(Aqs the right class
246 \& ok 3 \- sec()
247 \& ok 4 \- min()
248 \& ok 5 \- hour()
249 \& not ok 6 \- day()
250 \& # Failed test (\- at line 16)
251 \& ok 7 \- month()
252 \& ok 8 \- year()
253 \& # Looks like you failed 1 tests of 8.
254 .Ve
255 .PP
256 Whoops, a failure! [4] Test::Simple helpfully lets us know on what line the
257 failure occurred, but not much else. We were supposed to get 17, but we
258 didn\*(Aqt. What did we get?? Dunno. You could re\-run the test in the debugger
259 or throw in some print statements to find out.
260 .PP
261 Instead, switch from Test::Simple to Test::More. Test::More
262 does everything Test::Simple does, and more! In fact, Test::More does
263 things \fIexactly\fR the way Test::Simple does. You can literally swap
264 Test::Simple out and put Test::More in its place. That\*(Aqs just what
265 we\*(Aqre going to do.
266 .PP
267 Test::More does more than Test::Simple. The most important difference at
268 this point is it provides more informative ways to say "ok". Although you can
269 write almost any test with a generic \f(CWok()\fR, it can\*(Aqt tell you what went
270 wrong. The \f(CWis()\fR function lets us declare that something is supposed to be
271 the same as something else:
272 .PP
273 .Vb 1
274 \& use Test::More tests => 8;
275 \&
276 \& use Date::ICal;
277 \&
278 \& $ical = Date::ICal\->new( year => 1964, month => 10, day => 16,
279 \& hour => 16, min => 12, sec => 47,
280 \& tz => \*(Aq0530\*(Aq );
281 \&
282 \& ok( defined $ical, \*(Aqnew() returned something\*(Aq );
283 \& ok( $ical\->isa(\*(AqDate::ICal\*(Aq), " and it\*(Aqs the right class" );
284 \& is( $ical\->sec, 47, \*(Aq sec()\*(Aq );
285 \& is( $ical\->min, 12, \*(Aq min()\*(Aq );
286 \& is( $ical\->hour, 16, \*(Aq hour()\*(Aq );
287 \& is( $ical\->day, 17, \*(Aq day()\*(Aq );
288 \& is( $ical\->month, 10, \*(Aq month()\*(Aq );
289 \& is( $ical\->year, 1964, \*(Aq year()\*(Aq );
290 .Ve
291 .PP
292 "Is \f(CW\*(C`$ical\->sec\*(C'\fR 47?" "Is \f(CW\*(C`$ical\->min\*(C'\fR 12?" With \f(CWis()\fR in place,
293 you get more information:
294 .PP
295 .Vb 10
296 \& 1..8
297 \& ok 1 \- new() returned something
298 \& ok 2 \- and it\*(Aqs the right class
299 \& ok 3 \- sec()
300 \& ok 4 \- min()
301 \& ok 5 \- hour()
302 \& not ok 6 \- day()
303 \& # Failed test (\- at line 16)
304 \& # got: \*(Aq16\*(Aq
305 \& # expected: \*(Aq17\*(Aq
306 \& ok 7 \- month()
307 \& ok 8 \- year()
308 \& # Looks like you failed 1 tests of 8.
309 .Ve
310 .PP
311 Aha. \f(CW\*(C`$ical\->day\*(C'\fR returned 16, but we expected 17. A
312 quick check shows that the code is working fine, we made a mistake
313 when writing the tests. Change it to:
314 .PP
315 .Vb 1
316 \& is( $ical\->day, 16, \*(Aq day()\*(Aq );
317 .Ve
318 .PP
319 \&... and everything works.
320 .PP
321 Any time you\*(Aqre doing a "this equals that" sort of test, use \f(CWis()\fR.
322 It even works on arrays. The test is always in scalar context, so you
323 can test how many elements are in an array this way. [5]
324 .PP
325 .Vb 1
326 \& is( @foo, 5, \*(Aqfoo has 5 elements\*(Aq );
327 .Ve
328 .SS "Sometimes the tests are wrong"
329 .IX Subsection "Sometimes the tests are wrong"
330 This brings up a very important lesson. Code has bugs. Tests are
331 code. Ergo, tests have bugs. A failing test could mean a bug in the
332 code, but don\*(Aqt discount the possibility that the test is wrong.
333 .PP
334 On the flip side, don\*(Aqt be tempted to prematurely declare a test
335 incorrect just because you\*(Aqre having trouble finding the bug.
336 Invalidating a test isn\*(Aqt something to be taken lightly, and don\*(Aqt use
337 it as a cop out to avoid work.
338 .SS "Testing lots of values"
339 .IX Subsection "Testing lots of values"
340 We\*(Aqre going to be wanting to test a lot of dates here, trying to trick
341 the code with lots of different edge cases. Does it work before 1970?
342 After 2038? Before 1904? Do years after 10,000 give it trouble?
343 Does it get leap years right? We could keep repeating the code above,
344 or we could set up a little try/expect loop.
345 .PP
346 .Vb 2
347 \& use Test::More tests => 32;
348 \& use Date::ICal;
349 \&
350 \& my %ICal_Dates = (
351 \& # An ICal string And the year, month, day
352 \& # hour, minute and second we expect.
353 \& \*(Aq19971024T120000\*(Aq => # from the docs.
354 \& [ 1997, 10, 24, 12, 0, 0 ],
355 \& \*(Aq20390123T232832\*(Aq => # after the Unix epoch
356 \& [ 2039, 1, 23, 23, 28, 32 ],
357 \& \*(Aq19671225T000000\*(Aq => # before the Unix epoch
358 \& [ 1967, 12, 25, 0, 0, 0 ],
359 \& \*(Aq18990505T232323\*(Aq => # before the MacOS epoch
360 \& [ 1899, 5, 5, 23, 23, 23 ],
361 \& );
362 \&
363 \&
364 \& while( my($ical_str, $expect) = each %ICal_Dates ) {
365 \& my $ical = Date::ICal\->new( ical => $ical_str );
366 \&
367 \& ok( defined $ical, "new(ical => \*(Aq$ical_str\*(Aq)" );
368 \& ok( $ical\->isa(\*(AqDate::ICal\*(Aq), " and it\*(Aqs the right class" );
369 \&
370 \& is( $ical\->year, $expect\->[0], \*(Aq year()\*(Aq );
371 \& is( $ical\->month, $expect\->[1], \*(Aq month()\*(Aq );
372 \& is( $ical\->day, $expect\->[2], \*(Aq day()\*(Aq );
373 \& is( $ical\->hour, $expect\->[3], \*(Aq hour()\*(Aq );
374 \& is( $ical\->min, $expect\->[4], \*(Aq min()\*(Aq );
375 \& is( $ical\->sec, $expect\->[5], \*(Aq sec()\*(Aq );
376 \& }
377 .Ve
378 .PP
379 Now we can test bunches of dates by just adding them to
380 \&\f(CW%ICal_Dates\fR. Now that it\*(Aqs less work to test with more dates, you\*(Aqll
381 be inclined to just throw more in as you think of them.
382 Only problem is, every time we add to that we have to keep adjusting
383 the \f(CW\*(C`use Test::More tests => ##\*(C'\fR line. That can rapidly get
384 annoying. There are ways to make this work better.
385 .PP
386 First, we can calculate the plan dynamically using the \f(CWplan()\fR
387 function.
388 .PP
389 .Vb 2
390 \& use Test::More;
391 \& use Date::ICal;
392 \&
393 \& my %ICal_Dates = (
394 \& ...same as before...
395 \& );
396 \&
397 \& # For each key in the hash we\*(Aqre running 8 tests.
398 \& plan tests => keys(%ICal_Dates) * 8;
399 \&
400 \& ...and then your tests...
401 .Ve
402 .PP
403 To be even more flexible, use \f(CW\*(C`done_testing\*(C'\fR. This means we\*(Aqre just
404 running some tests, don\*(Aqt know how many. [6]
405 .PP
406 .Vb 1
407 \& use Test::More; # instead of tests => 32
408 \&
409 \& ... # tests here
410 \&
411 \& done_testing(); # reached the end safely
412 .Ve
413 .PP
414 If you don\*(Aqt specify a plan, Test::More expects to see \f(CWdone_testing()\fR
415 before your program exits. It will warn you if you forget it. You can give
416 \&\f(CWdone_testing()\fR an optional number of tests you expected to run, and if the
417 number ran differs, Test::More will give you another kind of warning.
418 .SS "Informative names"
419 .IX Subsection "Informative names"
420 Take a look at the line:
421 .PP
422 .Vb 1
423 \& ok( defined $ical, "new(ical => \*(Aq$ical_str\*(Aq)" );
424 .Ve
425 .PP
426 We\*(Aqve added more detail about what we\*(Aqre testing and the ICal string
427 itself we\*(Aqre trying out to the name. So you get results like:
428 .PP
429 .Vb 8
430 \& ok 25 \- new(ical => \*(Aq19971024T120000\*(Aq)
431 \& ok 26 \- and it\*(Aqs the right class
432 \& ok 27 \- year()
433 \& ok 28 \- month()
434 \& ok 29 \- day()
435 \& ok 30 \- hour()
436 \& ok 31 \- min()
437 \& ok 32 \- sec()
438 .Ve
439 .PP
440 If something in there fails, you\*(Aqll know which one it was and that
441 will make tracking down the problem easier. Try to put a bit of
442 debugging information into the test names.
443 .PP
444 Describe what the tests test, to make debugging a failed test easier
445 for you or for the next person who runs your test.
446 .SS "Skipping tests"
447 .IX Subsection "Skipping tests"
448 Poking around in the existing Date::ICal tests, I found this in
449 \&\fIt/01sanity.t\fR [7]
450 .PP
451 .Vb 1
452 \& #!/usr/bin/perl \-w
453 \&
454 \& use Test::More tests => 7;
455 \& use Date::ICal;
456 \&
457 \& # Make sure epoch time is being handled sanely.
458 \& my $t1 = Date::ICal\->new( epoch => 0 );
459 \& is( $t1\->epoch, 0, "Epoch time of 0" );
460 \&
461 \& # XXX This will only work on unix systems.
462 \& is( $t1\->ical, \*(Aq19700101Z\*(Aq, " epoch to ical" );
463 \&
464 \& is( $t1\->year, 1970, " year()" );
465 \& is( $t1\->month, 1, " month()" );
466 \& is( $t1\->day, 1, " day()" );
467 \&
468 \& # like the tests above, but starting with ical instead of epoch
469 \& my $t2 = Date::ICal\->new( ical => \*(Aq19700101Z\*(Aq );
470 \& is( $t2\->ical, \*(Aq19700101Z\*(Aq, "Start of epoch in ICal notation" );
471 \&
472 \& is( $t2\->epoch, 0, " and back to ICal" );
473 .Ve
474 .PP
475 The beginning of the epoch is different on most non\-Unix operating systems [8].
476 Even though Perl smooths out the differences for the most part, certain ports
477 do it differently. MacPerl is one off the top of my head. [9] Rather than
478 putting a comment in the test and hoping someone will read the test while
479 debugging the failure, we can explicitly say it\*(Aqs never going to work and skip
480 the test.
481 .PP
482 .Vb 2
483 \& use Test::More tests => 7;
484 \& use Date::ICal;
485 \&
486 \& # Make sure epoch time is being handled sanely.
487 \& my $t1 = Date::ICal\->new( epoch => 0 );
488 \& is( $t1\->epoch, 0, "Epoch time of 0" );
489 \&
490 \& SKIP: {
491 \& skip(\*(Aqepoch to ICal not working on Mac OS\*(Aq, 6)
492 \& if $^O eq \*(AqMacOS\*(Aq;
493 \&
494 \& is( $t1\->ical, \*(Aq19700101Z\*(Aq, " epoch to ical" );
495 \&
496 \& is( $t1\->year, 1970, " year()" );
497 \& is( $t1\->month, 1, " month()" );
498 \& is( $t1\->day, 1, " day()" );
499 \&
500 \& # like the tests above, but starting with ical instead of epoch
501 \& my $t2 = Date::ICal\->new( ical => \*(Aq19700101Z\*(Aq );
502 \& is( $t2\->ical, \*(Aq19700101Z\*(Aq, "Start of epoch in ICal notation" );
503 \&
504 \& is( $t2\->epoch, 0, " and back to ICal" );
505 \& }
506 .Ve
507 .PP
508 A little bit of magic happens here. When running on anything but MacOS, all
509 the tests run normally. But when on MacOS, \f(CWskip()\fR causes the entire
510 contents of the SKIP block to be jumped over. It never runs. Instead,
511 \&\f(CWskip()\fR prints special output that tells Test::Harness that the tests have
512 been skipped.
513 .PP
514 .Vb 8
515 \& 1..7
516 \& ok 1 \- Epoch time of 0
517 \& ok 2 # skip epoch to ICal not working on MacOS
518 \& ok 3 # skip epoch to ICal not working on MacOS
519 \& ok 4 # skip epoch to ICal not working on MacOS
520 \& ok 5 # skip epoch to ICal not working on MacOS
521 \& ok 6 # skip epoch to ICal not working on MacOS
522 \& ok 7 # skip epoch to ICal not working on MacOS
523 .Ve
524 .PP
525 This means your tests won\*(Aqt fail on MacOS. This means fewer emails
526 from MacPerl users telling you about failing tests that you know will
527 never work. You\*(Aqve got to be careful with skip tests. These are for
528 tests which don\*(Aqt work and \fInever will\fR. It is not for skipping
529 genuine bugs (we\*(Aqll get to that in a moment).
530 .PP
531 The tests are wholly and completely skipped. [10] This will work.
532 .PP
533 .Vb 2
534 \& SKIP: {
535 \& skip("I don\*(Aqt wanna die!");
536 \&
537 \& die, die, die, die, die;
538 \& }
539 .Ve
540 .SS "Todo tests"
541 .IX Subsection "Todo tests"
542 While thumbing through the Date::ICal man page, I came across this:
543 .PP
544 .Vb 1
545 \& ical
546 \&
547 \& $ical_string = $ical\->ical;
548 \&
549 \& Retrieves, or sets, the date on the object, using any
550 \& valid ICal date/time string.
551 .Ve
552 .PP
553 "Retrieves or sets". Hmmm. I didn\*(Aqt see a test for using \f(CWical()\fR to set
554 the date in the Date::ICal test suite. So I wrote one:
555 .PP
556 .Vb 2
557 \& use Test::More tests => 1;
558 \& use Date::ICal;
559 \&
560 \& my $ical = Date::ICal\->new;
561 \& $ical\->ical(\*(Aq20201231Z\*(Aq);
562 \& is( $ical\->ical, \*(Aq20201231Z\*(Aq, \*(AqSetting via ical()\*(Aq );
563 .Ve
564 .PP
565 Run that. I saw:
566 .PP
567 .Vb 6
568 \& 1..1
569 \& not ok 1 \- Setting via ical()
570 \& # Failed test (\- at line 6)
571 \& # got: \*(Aq20010814T233649Z\*(Aq
572 \& # expected: \*(Aq20201231Z\*(Aq
573 \& # Looks like you failed 1 tests of 1.
574 .Ve
575 .PP
576 Whoops! Looks like it\*(Aqs unimplemented. Assume you don\*(Aqt have the time to fix
577 this. [11] Normally, you\*(Aqd just comment out the test and put a note in a todo
578 list somewhere. Instead, explicitly state "this test will fail" by wrapping it
579 in a \f(CW\*(C`TODO\*(C'\fR block:
580 .PP
581 .Vb 1
582 \& use Test::More tests => 1;
583 \&
584 \& TODO: {
585 \& local $TODO = \*(Aqical($ical) not yet implemented\*(Aq;
586 \&
587 \& my $ical = Date::ICal\->new;
588 \& $ical\->ical(\*(Aq20201231Z\*(Aq);
589 \&
590 \& is( $ical\->ical, \*(Aq20201231Z\*(Aq, \*(AqSetting via ical()\*(Aq );
591 \& }
592 .Ve
593 .PP
594 Now when you run, it\*(Aqs a little different:
595 .PP
596 .Vb 4
597 \& 1..1
598 \& not ok 1 \- Setting via ical() # TODO ical($ical) not yet implemented
599 \& # got: \*(Aq20010822T201551Z\*(Aq
600 \& # expected: \*(Aq20201231Z\*(Aq
601 .Ve
602 .PP
603 Test::More doesn\*(Aqt say "Looks like you failed 1 tests of 1". That \*(Aq#
604 TODO\*(Aq tells Test::Harness "this is supposed to fail" and it treats a
605 failure as a successful test. You can write tests even before
606 you\*(Aqve fixed the underlying code.
607 .PP
608 If a TODO test passes, Test::Harness will report it "UNEXPECTEDLY
609 SUCCEEDED". When that happens, remove the TODO block with \f(CW\*(C`local $TODO\*(C'\fR and
610 turn it into a real test.
611 .SS "Testing with taint mode."
612 .IX Subsection "Testing with taint mode."
613 Taint mode is a funny thing. It\*(Aqs the globalest of all global
614 features. Once you turn it on, it affects \fIall\fR code in your program
615 and \fIall\fR modules used (and all the modules they use). If a single
616 piece of code isn\*(Aqt taint clean, the whole thing explodes. With that
617 in mind, it\*(Aqs very important to ensure your module works under taint
618 mode.
619 .PP
620 It\*(Aqs very simple to have your tests run under taint mode. Just throw
621 a \f(CW\*(C`\-T\*(C'\fR into the \f(CW\*(C`#!\*(C'\fR line. Test::Harness will read the switches
622 in \f(CW\*(C`#!\*(C'\fR and use them to run your tests.
623 .PP
624 .Vb 1
625 \& #!/usr/bin/perl \-Tw
626 \&
627 \& ...test normally here...
628 .Ve
629 .PP
630 When you say \f(CW\*(C`make test\*(C'\fR it will run with taint mode on.
631 .SH FOOTNOTES
632 .IX Header "FOOTNOTES"
633 .IP 1. 4
634 The first number doesn\*(Aqt really mean anything, but it has to be 1.
635 It\*(Aqs the second number that\*(Aqs important.
636 .IP 2. 4
637 For those following along at home, I\*(Aqm using version 1.31. It has
638 some bugs, which is good \-\- we\*(Aqll uncover them with our tests.
639 .IP 3. 4
640 You can actually take this one step further and test the manual
641 itself. Have a look at Test::Inline (formerly Pod::Tests).
642 .IP 4. 4
643 Yes, there\*(Aqs a mistake in the test suite. What! Me, contrived?
644 .IP 5. 4
645 We\*(Aqll get to testing the contents of lists later.
646 .IP 6. 4
647 But what happens if your test program dies halfway through?! Since we
648 didn\*(Aqt say how many tests we\*(Aqre going to run, how can we know it
649 failed? No problem, Test::More employs some magic to catch that death
650 and turn the test into a failure, even if every test passed up to that
651 point.
652 .IP 7. 4
653 I cleaned it up a little.
654 .IP 8. 4
655 Most Operating Systems record time as the number of seconds since a
656 certain date. This date is the beginning of the epoch. Unix\*(Aqs starts
657 at midnight January 1st, 1970 GMT.
658 .IP 9. 4
659 MacOS\*(Aqs epoch is midnight January 1st, 1904. VMS\*(Aqs is midnight,
660 November 17th, 1858, but vmsperl emulates the Unix epoch so it\*(Aqs not a
661 problem.
662 .IP 10. 4
663 As long as the code inside the SKIP block at least compiles. Please
664 don\*(Aqt ask how. No, it\*(Aqs not a filter.
665 .IP 11. 4
666 Do NOT be tempted to use TODO tests as a way to avoid fixing simple
667 bugs!
668 .SH AUTHORS
669 .IX Header "AUTHORS"
670 Michael G Schwern <[email protected]> and the perl\-qa dancers!
671 .SH MAINTAINERS
672 .IX Header "MAINTAINERS"
673 .IP "Chad Granum <[email protected]>" 4
674 .IX Item "Chad Granum <[email protected]>"
675 .SH COPYRIGHT
676 .IX Header "COPYRIGHT"
677 Copyright 2001 by Michael G Schwern <[email protected]>.
678 .PP
679 This documentation is free; you can redistribute it and/or modify it
680 under the same terms as Perl itself.
681 .PP
682 Irrespective of its distribution, all code examples in these files
683 are hereby placed into the public domain. You are permitted and
684 encouraged to use this code in your own programs for fun
685 or for profit as you see fit. A simple comment in the code giving
686 credit would be courteous but is not required.