Debian Codegraph @

upstream/debian-unstable/man3/Test::Tutorial.3perl

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