0
  #   €l–Я=їJJj"T НА‚г.©‹FяЗ„мґзїД ?ч     =head1 NAME

Test::Tutorial - A tutorial about writing really basic tests

=head1 DESCRIPTION


I<AHHHHHHH!!!!  NOT TESTING!  Anything but testing!
Beat me, whip me, send me to Detroit, but don't make
me write tests!>

I<*sob*>

I<Besides, I don't know how to write the damned things.>


Is this you?  Is writing tests right up there with writing
documentation and having your fingernails pulled out?  Did you open up
a test and read

    ######## We start with some black magic

and decide that's quite enough for you?

It's ok.  That's all gone now.  We've done all the black magic for
you.  And here are the tricks...


=head2 Nuts and bolts of testing.

Here's the most basic test program.

    #!/usr/bin/perl -w

    print "1..1\n";

    print 1 + 1 == 2 ? "ok 1\n" : "not ok 1\n";

Because 1 + 1 is 2, it prints:

    1..1
    ok 1

What this says is: C<1..1> "I'm going to run one test." [1] C<ok 1>
"The first test passed".  And that's about all magic there is to
testing.  Your basic unit of testing is the I<ok>.  For each thing you
test, an C<ok> is printed.  Simple.  L<Test::Harness> interprets your test
results to determine if you succeeded or failed (more on that later).

Writing all these print statements rapidly gets tedious.  Fortunately,
there's L<Test::Simple>.  It has one function, C<ok()>.

    #!/usr/bin/perl -w

    use Test::Simple tests => 1;

    ok( 1 + 1 == 2 );

That does the same thing as the previous code.  C<ok()> is the backbone
of Perl testing, and we'll be using it instead of roll-your-own from
here on.  If C<ok()> gets a true value, the test passes.  False, it
fails.

    #!/usr/bin/perl -w

    use Test::Simple tests => 2;
    ok( 1 + 1 == 2 );
    ok( 2 + 2 == 5 );

From that comes:

    1..2
    ok 1
    not ok 2
    #     Failed test (test.pl at line 5)
    # Looks like you failed 1 tests of 2.

C<1..2> "I'm going to run two tests."  This number is a I<plan>. It helps to
ensure your test program ran all the way through and didn't die or skip some
tests.  C<ok 1> "The first test passed."  C<not ok 2> "The second test failed".
Test::Simple helpfully prints out some extra commentary about your tests.

It's not scary.  Come, hold my hand.  We're going to give an example
of testing a module.  For our example, we'll be testing a date
library, L<Date::ICal>.  It's on CPAN, so download a copy and follow
along. [2]


=head2 Where to start?

This is the hardest part of testing, where do you start?  People often get
overwhelmed at the apparent enormity of the task of testing a whole module.
The best place to start is at the beginning.  L<Date::ICal> is an
object-oriented module, and that means you start by making an object.  Test
C<new()>.

    #!/usr/bin/perl -w

    # assume these two lines are in all subsequent examples
    use strict;
    use warnings;

    use Test::Simple tests => 2;

    use Date::ICal;

    my $ical = Date::ICal->new;         # create an object
    ok( defined $ical );                # check that we got something
    ok( $ical->isa('Date::ICal') );     # and it's the right class

Run that and you should get:

    1..2
    ok 1
    ok 2

Congratulations! You've written your first useful test.


=head2 Names

That output isn't terribly descriptive, is it?  When you have two tests you can
figure out which one is #2, but what if you have 102 tests?

Each test can be given a little descriptive name as the second
argument to C<ok()>.

    use Test::Simple tests => 2;

    ok( defined $ical,              'new() returned something' );
    ok( $ical->isa('Date::ICal'),   "  and it's the right class" );

Now you'll see:

    1..2
    ok 1 - new() returned something
    ok 2 -   and it's the right class


=head2 Test the manual

The simplest way to build up a decent testing suite is to just test what
the manual says it does. [3] Let's pull something out of the
L<Date::ICal/SYNOPSIS> and test that all its bits work.

    #!/usr/bin/perl -w

    use Test::Simple tests => 8;

    use Date::ICal;

    $ical = Date::ICal->new( year => 1964, mon