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