1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
4 .\" ========================================================================
5 .de Sh \" Subsection heading
13 .de Sp \" Vertical space (when we can't use .PP)
17 .de Vb \" Begin verbatim text
22 .de Ve \" End verbatim text
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<>.
33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
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
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.
57 . tm Index:\\$1\t\\n%\t"\\$2"
63 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
64 .\" way too many mistakes in technical documents.
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
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
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'
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 \
129 .\" ========================================================================
131 .IX Title "Test::Tutorial 3"
132 .TH Test::Tutorial 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
134 Test::Tutorial \- A tutorial about writing really basic tests
136 .IX Header "DESCRIPTION"
137 \&\fI\s-1AHHHHHHH\s0!!!! \s-1NOT\s0 \s-1TESTING\s0! Anything but testing!
138 Beat me, whip me, send me to Detroit, but don't make
143 \&\fIBesides, I don't know how to write the damned things.\fR
145 Is this you? Is writing tests right up there with writing
146 documentation and having your fingernails pulled out? Did you open up
150 \& ######## We start with some black magic
153 and decide that's quite enough for you?
155 It's ok. That's all gone now. We've done all the black magic for
156 you. And here are the tricks...
157 .Sh "Nuts and bolts of testing."
158 .IX Subsection "Nuts and bolts of testing."
159 Here's the most basic test program.
162 \& #!/usr/bin/perl \-w
170 \& print 1 + 1 == 2 ? "ok 1\en" : "not ok 1\en";
173 since 1 + 1 is 2, it prints:
180 What this says is: \f(CW1..1\fR \*(L"I'm going to run one test.\*(R" [1] \f(CW\*(C`ok 1\*(C'\fR
181 \&\*(L"The first test passed\*(R". And that's about all magic there is to
182 testing. Your basic unit of testing is the \fIok\fR. For each thing you
183 test, an \f(CW\*(C`ok\*(C'\fR is printed. Simple. \fBTest::Harness\fR interprets your test
184 results to determine if you succeeded or failed (more on that later).
186 Writing all these print statements rapidly gets tedious. Fortunately,
187 there's \fBTest::Simple\fR. It has one function, \f(CW\*(C`ok()\*(C'\fR.
190 \& #!/usr/bin/perl \-w
194 \& use Test::Simple tests => 1;
201 and that does the same thing as the code above. \f(CW\*(C`ok()\*(C'\fR is the backbone
202 of Perl testing, and we'll be using it instead of roll-your-own from
203 here on. If \f(CW\*(C`ok()\*(C'\fR gets a true value, the test passes. False, it
207 \& #!/usr/bin/perl \-w
211 \& use Test::Simple tests => 2;
222 \& # Failed test (test.pl at line 5)
223 \& # Looks like you failed 1 tests of 2.
226 \&\f(CW1..2\fR \*(L"I'm going to run two tests.\*(R" This number is used to ensure
227 your test program ran all the way through and didn't die or skip some
228 tests. \f(CW\*(C`ok 1\*(C'\fR \*(L"The first test passed.\*(R" \f(CW\*(C`not ok 2\*(C'\fR \*(L"The second test
229 failed\*(R". Test::Simple helpfully prints out some extra commentary about
232 It's not scary. Come, hold my hand. We're going to give an example
233 of testing a module. For our example, we'll be testing a date
234 library, \fBDate::ICal\fR. It's on \s-1CPAN\s0, so download a copy and follow
236 .Sh "Where to start?"
237 .IX Subsection "Where to start?"
238 This is the hardest part of testing, where do you start? People often
239 get overwhelmed at the apparent enormity of the task of testing a
240 whole module. Best place to start is at the beginning. Date::ICal is
241 an object-oriented module, and that means you start by making an
242 object. So we test \f(CW\*(C`new()\*(C'\fR.
245 \& #!/usr/bin/perl \-w
249 \& use Test::Simple tests => 2;
257 \& my $ical = Date::ICal\->new; # create an object
258 \& ok( defined $ical ); # check that we got something
259 \& ok( $ical\->isa('Date::ICal') ); # and it's the right class
262 run that and you should get:
270 congratulations, you've written your first useful test.
272 .IX Subsection "Names"
273 That output isn't terribly descriptive, is it? When you have two
274 tests you can figure out which one is #2, but what if you have 102?
276 Each test can be given a little descriptive name as the second
277 argument to \f(CW\*(C`ok()\*(C'\fR.
280 \& use Test::Simple tests => 2;
284 \& ok( defined $ical, 'new() returned something' );
285 \& ok( $ical\->isa('Date::ICal'), " and it's the right class" );
292 \& ok 1 \- new() returned something
293 \& ok 2 \- and it's the right class
295 .Sh "Test the manual"
296 .IX Subsection "Test the manual"
297 Simplest way to build up a decent testing suite is to just test what
298 the manual says it does. [3] Let's pull something out of the
299 \&\*(L"\s-1SYNOPSIS\s0\*(R" in Date::ICal and test that all its bits work.
302 \& #!/usr/bin/perl \-w
306 \& use Test::Simple tests => 8;
314 \& $ical = Date::ICal\->new( year => 1964, month => 10, day => 16,
315 \& hour => 16, min => 12, sec => 47,
320 \& ok( defined $ical, 'new() returned something' );
321 \& ok( $ical\->isa('Date::ICal'), " and it's the right class" );
322 \& ok( $ical\->sec == 47, ' sec()' );
323 \& ok( $ical\->min == 12, ' min()' );
324 \& ok( $ical\->hour == 16, ' hour()' );
325 \& ok( $ical\->day == 17, ' day()' );
326 \& ok( $ical\->month == 10, ' month()' );
327 \& ok( $ical\->year == 1964, ' year()' );
330 run that and you get:
334 \& ok 1 \- new() returned something
335 \& ok 2 \- and it's the right class
340 \& # Failed test (\- at line 16)
343 \& # Looks like you failed 1 tests of 8.
346 Whoops, a failure! [4] Test::Simple helpfully lets us know on what line
347 the failure occurred, but not much else. We were supposed to get 17,
348 but we didn't. What did we get?? Dunno. We'll have to re-run the
349 test in the debugger or throw in some print statements to find out.
351 Instead, we'll switch from \fBTest::Simple\fR to \fBTest::More\fR. \fBTest::More\fR
352 does everything \fBTest::Simple\fR does, and more! In fact, Test::More does
353 things \fIexactly\fR the way Test::Simple does. You can literally swap
354 Test::Simple out and put Test::More in its place. That's just what
357 Test::More does more than Test::Simple. The most important difference
358 at this point is it provides more informative ways to say \*(L"ok\*(R".
359 Although you can write almost any test with a generic \f(CW\*(C`ok()\*(C'\fR, it
360 can't tell you what went wrong. Instead, we'll use the \f(CW\*(C`is()\*(C'\fR
361 function, which lets us declare that something is supposed to be the
362 same as something else:
365 \& #!/usr/bin/perl \-w
369 \& use Test::More tests => 8;
377 \& $ical = Date::ICal\->new( year => 1964, month => 10, day => 16,
378 \& hour => 16, min => 12, sec => 47,
383 \& ok( defined $ical, 'new() returned something' );
384 \& ok( $ical\->isa('Date::ICal'), " and it's the right class" );
385 \& is( $ical\->sec, 47, ' sec()' );
386 \& is( $ical\->min, 12, ' min()' );
387 \& is( $ical\->hour, 16, ' hour()' );
388 \& is( $ical\->day, 17, ' day()' );
389 \& is( $ical\->month, 10, ' month()' );
390 \& is( $ical\->year, 1964, ' year()' );
393 "Is \f(CW\*(C`$ical\->sec\*(C'\fR 47?\*(L" \*(R"Is \f(CW\*(C`$ical\->min\*(C'\fR 12?" With \f(CW\*(C`is()\*(C'\fR in place,
394 you get some more information
398 \& ok 1 \- new() returned something
399 \& ok 2 \- and it's the right class
404 \& # Failed test (\- at line 16)
409 \& # Looks like you failed 1 tests of 8.
412 letting us know that \f(CW\*(C`$ical\->day\*(C'\fR returned 16, but we expected 17. A
413 quick check shows that the code is working fine, we made a mistake
414 when writing up the tests. Just change it to:
417 \& is( $ical\->day, 16, ' day()' );
420 and everything works.
422 So any time you're doing a \*(L"this equals that\*(R" sort of test, use \f(CW\*(C`is()\*(C'\fR.
423 It even works on arrays. The test is always in scalar context, so you
424 can test how many elements are in a list this way. [5]
427 \& is( @foo, 5, 'foo has 5 elements' );
429 .Sh "Sometimes the tests are wrong"
430 .IX Subsection "Sometimes the tests are wrong"
431 Which brings us to a very important lesson. Code has bugs. Tests are
432 code. Ergo, tests have bugs. A failing test could mean a bug in the
433 code, but don't discount the possibility that the test is wrong.
435 On the flip side, don't be tempted to prematurely declare a test
436 incorrect just because you're having trouble finding the bug.
437 Invalidating a test isn't something to be taken lightly, and don't use
438 it as a cop out to avoid work.
439 .Sh "Testing lots of values"
440 .IX Subsection "Testing lots of values"
441 We're going to be wanting to test a lot of dates here, trying to trick
442 the code with lots of different edge cases. Does it work before 1970?
443 After 2038? Before 1904? Do years after 10,000 give it trouble?
444 Does it get leap years right? We could keep repeating the code above,
445 or we could set up a little try/expect loop.
448 \& use Test::More tests => 32;
453 \& my %ICal_Dates = (
454 \& # An ICal string And the year, month, day
455 \& # hour, minute and second we expect.
456 \& '19971024T120000' => # from the docs.
457 \& [ 1997, 10, 24, 12, 0, 0 ],
458 \& '20390123T232832' => # after the Unix epoch
459 \& [ 2039, 1, 23, 23, 28, 32 ],
460 \& '19671225T000000' => # before the Unix epoch
461 \& [ 1967, 12, 25, 0, 0, 0 ],
462 \& '18990505T232323' => # before the MacOS epoch
463 \& [ 1899, 5, 5, 23, 23, 23 ],
468 \& while( my($ical_str, $expect) = each %ICal_Dates ) {
469 \& my $ical = Date::ICal\->new( ical => $ical_str );
473 \& ok( defined $ical, "new(ical => '$ical_str')" );
474 \& ok( $ical\->isa('Date::ICal'), " and it's the right class" );
478 \& is( $ical\->year, $expect\->[0], ' year()' );
479 \& is( $ical\->month, $expect\->[1], ' month()' );
480 \& is( $ical\->day, $expect\->[2], ' day()' );
481 \& is( $ical\->hour, $expect\->[3], ' hour()' );
482 \& is( $ical\->min, $expect\->[4], ' min()' );
483 \& is( $ical\->sec, $expect\->[5], ' sec()' );
487 So now we can test bunches of dates by just adding them to
488 \&\f(CW%ICal_Dates\fR. Now that it's less work to test with more dates, you'll
489 be inclined to just throw more in as you think of them.
490 Only problem is, every time we add to that we have to keep adjusting
491 the \f(CW\*(C`use Test::More tests => ##\*(C'\fR line. That can rapidly get
492 annoying. There's two ways to make this work better.
494 First, we can calculate the plan dynamically using the \f(CW\*(C`plan()\*(C'\fR
503 \& my %ICal_Dates = (
504 \& ...same as before...
509 \& # For each key in the hash we're running 8 tests.
510 \& plan tests => keys(%ICal_Dates) * 8;
514 \& ...and then your tests...
517 Or to be even more flexible, we use \f(CW\*(C`no_plan\*(C'\fR. This means we're just
518 running some tests, don't know how many. [6]
521 \& use Test::More 'no_plan'; # instead of tests => 32
524 now we can just add tests and not have to do all sorts of math to
525 figure out how many we're running.
526 .Sh "Informative names"
527 .IX Subsection "Informative names"
528 Take a look at this line here
531 \& ok( defined $ical, "new(ical => '$ical_str')" );
534 we've added more detail about what we're testing and the ICal string
535 itself we're trying out to the name. So you get results like:
538 \& ok 25 \- new(ical => '19971024T120000')
539 \& ok 26 \- and it's the right class
548 if something in there fails, you'll know which one it was and that
549 will make tracking down the problem easier. So try to put a bit of
550 debugging information into the test names.
552 Describe what the tests test, to make debugging a failed test easier
553 for you or for the next person who runs your test.
555 .IX Subsection "Skipping tests"
556 Poking around in the existing Date::ICal tests, I found this in
557 \&\fIt/01sanity.t\fR [7]
560 \& #!/usr/bin/perl \-w
564 \& use Test::More tests => 7;
569 \& # Make sure epoch time is being handled sanely.
570 \& my $t1 = Date::ICal\->new( epoch => 0 );
571 \& is( $t1\->epoch, 0, "Epoch time of 0" );
575 \& # XXX This will only work on unix systems.
576 \& is( $t1\->ical, '19700101Z', " epoch to ical" );
580 \& is( $t1\->year, 1970, " year()" );
581 \& is( $t1\->month, 1, " month()" );
582 \& is( $t1\->day, 1, " day()" );
586 \& # like the tests above, but starting with ical instead of epoch
587 \& my $t2 = Date::ICal\->new( ical => '19700101Z' );
588 \& is( $t2\->ical, '19700101Z', "Start of epoch in ICal notation" );
592 \& is( $t2\->epoch, 0, " and back to ICal" );
595 The beginning of the epoch is different on most non-Unix operating
596 systems [8]. Even though Perl smooths out the differences for the
597 most part, certain ports do it differently. MacPerl is one off the
598 top of my head. [9] So rather than just putting a comment in the test,
599 we can explicitly say it's never going to work and skip the test.
602 \& use Test::More tests => 7;
607 \& # Make sure epoch time is being handled sanely.
608 \& my $t1 = Date::ICal\->new( epoch => 0 );
609 \& is( $t1\->epoch, 0, "Epoch time of 0" );
614 \& skip('epoch to ICal not working on MacOS', 6)
615 \& if $^O eq 'MacOS';
619 \& is( $t1\->ical, '19700101Z', " epoch to ical" );
623 \& is( $t1\->year, 1970, " year()" );
624 \& is( $t1\->month, 1, " month()" );
625 \& is( $t1\->day, 1, " day()" );
629 \& # like the tests above, but starting with ical instead of epoch
630 \& my $t2 = Date::ICal\->new( ical => '19700101Z' );
631 \& is( $t2\->ical, '19700101Z', "Start of epoch in ICal notation" );
635 \& is( $t2\->epoch, 0, " and back to ICal" );
639 A little bit of magic happens here. When running on anything but
640 MacOS, all the tests run normally. But when on MacOS, \f(CW\*(C`skip()\*(C'\fR causes
641 the entire contents of the \s-1SKIP\s0 block to be jumped over. It's never
642 run. Instead, it prints special output that tells Test::Harness that
643 the tests have been skipped.
647 \& ok 1 \- Epoch time of 0
648 \& ok 2 # skip epoch to ICal not working on MacOS
649 \& ok 3 # skip epoch to ICal not working on MacOS
650 \& ok 4 # skip epoch to ICal not working on MacOS
651 \& ok 5 # skip epoch to ICal not working on MacOS
652 \& ok 6 # skip epoch to ICal not working on MacOS
653 \& ok 7 # skip epoch to ICal not working on MacOS
656 This means your tests won't fail on MacOS. This means less emails
657 from MacPerl users telling you about failing tests that you know will
658 never work. You've got to be careful with skip tests. These are for
659 tests which don't work and \fInever will\fR. It is not for skipping
660 genuine bugs (we'll get to that in a moment).
662 The tests are wholly and completely skipped. [10] This will work.
666 \& skip("I don't wanna die!");
670 \& die, die, die, die, die;
674 .IX Subsection "Todo tests"
675 Thumbing through the Date::ICal man page, I came across this:
682 \& $ical_string = $ical\->ical;
686 \& Retrieves, or sets, the date on the object, using any
687 \& valid ICal date/time string.
690 \&\*(L"Retrieves or sets\*(R". Hmmm, didn't see a test for using \f(CW\*(C`ical()\*(C'\fR to set
691 the date in the Date::ICal test suite. So I'll write one.
694 \& use Test::More tests => 1;
699 \& my $ical = Date::ICal\->new;
700 \& $ical\->ical('20201231Z');
701 \& is( $ical\->ical, '20201231Z', 'Setting via ical()' );
708 \& not ok 1 \- Setting via ical()
709 \& # Failed test (\- at line 6)
710 \& # got: '20010814T233649Z'
711 \& # expected: '20201231Z'
712 \& # Looks like you failed 1 tests of 1.
715 Whoops! Looks like it's unimplemented. Let's assume we don't have
716 the time to fix this. [11] Normally, you'd just comment out the test
717 and put a note in a todo list somewhere. Instead, we're going to
718 explicitly state \*(L"this test will fail\*(R" by wrapping it in a \f(CW\*(C`TODO\*(C'\fR block.
721 \& use Test::More tests => 1;
726 \& local $TODO = 'ical($ical) not yet implemented';
730 \& my $ical = Date::ICal\->new;
731 \& $ical\->ical('20201231Z');
735 \& is( $ical\->ical, '20201231Z', 'Setting via ical()' );
739 Now when you run, it's a little different:
743 \& not ok 1 \- Setting via ical() # TODO ical($ical) not yet implemented
744 \& # got: '20010822T201551Z'
745 \& # expected: '20201231Z'
748 Test::More doesn't say \*(L"Looks like you failed 1 tests of 1\*(R". That '#
749 \&\s-1TODO\s0' tells Test::Harness \*(L"this is supposed to fail\*(R" and it treats a
750 failure as a successful test. So you can write tests even before
751 you've fixed the underlying code.
753 If a \s-1TODO\s0 test passes, Test::Harness will report it \*(L"\s-1UNEXPECTEDLY\s0
754 \&\s-1SUCCEEDED\s0\*(R". When that happens, you simply remove the \s-1TODO\s0 block with
755 \&\f(CW\*(C`local $TODO\*(C'\fR and turn it into a real test.
756 .Sh "Testing with taint mode."
757 .IX Subsection "Testing with taint mode."
758 Taint mode is a funny thing. It's the globalest of all global
759 features. Once you turn it on, it affects \fIall\fR code in your program
760 and \fIall\fR modules used (and all the modules they use). If a single
761 piece of code isn't taint clean, the whole thing explodes. With that
762 in mind, it's very important to ensure your module works under taint
765 It's very simple to have your tests run under taint mode. Just throw
766 a \f(CW\*(C`\-T\*(C'\fR into the \f(CW\*(C`#!\*(C'\fR line. Test::Harness will read the switches
767 in \f(CW\*(C`#!\*(C'\fR and use them to run your tests.
770 \& #!/usr/bin/perl \-Tw
774 \& ...test normally here...
777 So when you say \f(CW\*(C`make test\*(C'\fR it will be run with taint mode and
780 .IX Header "FOOTNOTES"
783 The first number doesn't really mean anything, but it has to be 1.
784 It's the second number that's important.
787 For those following along at home, I'm using version 1.31. It has
788 some bugs, which is good \*(-- we'll uncover them with our tests.
791 You can actually take this one step further and test the manual
792 itself. Have a look at \fBTest::Inline\fR (formerly \fBPod::Tests\fR).
795 Yes, there's a mistake in the test suite. What! Me, contrived?
798 We'll get to testing the contents of lists later.
801 But what happens if your test program dies halfway through?! Since we
802 didn't say how many tests we're going to run, how can we know it
803 failed? No problem, Test::More employs some magic to catch that death
804 and turn the test into a failure, even if every test passed up to that
808 I cleaned it up a little.
811 Most Operating Systems record time as the number of seconds since a
812 certain date. This date is the beginning of the epoch. Unix's starts
813 at midnight January 1st, 1970 \s-1GMT\s0.
816 MacOS's epoch is midnight January 1st, 1904. \s-1VMS\s0's is midnight,
817 November 17th, 1858, but vmsperl emulates the Unix epoch so it's not a
821 As long as the code inside the \s-1SKIP\s0 block at least compiles. Please
822 don't ask how. No, it's not a filter.
825 Do \s-1NOT\s0 be tempted to use \s-1TODO\s0 tests as a way to avoid fixing simple
829 Michael G Schwern <schwern@pobox.com> and the perl-qa dancers!
831 .IX Header "COPYRIGHT"
832 Copyright 2001 by Michael G Schwern <schwern@pobox.com>.
834 This documentation is free; you can redistribute it and/or modify it
835 under the same terms as Perl itself.
837 Irrespective of its distribution, all code examples in these files
838 are hereby placed into the public domain. You are permitted and
839 encouraged to use this code in your own programs for fun
840 or for profit as you see fit. A simple comment in the code giving
841 credit would be courteous but is not required.
projects / catagits/Gitalist.git / blob