test::inline(3)

NAME

Test::Inline - Inlining your tests next to the code being
tested.

SYNOPSIS

LOOK AT Test::Inline::Tutorial FIRST!
   =item B<is_pirate>
        @pirates = is_pirate(@arrrgs);
    Go through @arrrgs and return a list of pirates.
    =begin testing
    my  @p  =  is_pirate('Blargbeard',  'Alfonse',  'Capt.
Hampton', 'Wesley');
    is(@p,  2,   "Found two pirates.  ARRR!");
    =end testing
    =cut
    sub is_pirate {
        ....
    }

DESCRIPTION

LOOK AT Test::Inline::Tutorial FIRST!

Embedding tests allows tests to be placed near the code
its testing. This is a nice supplement to the traditional
.t files. It's like XUnit, Perl-style.

Test::Tutorial is just documentation. To actually get
anything done you use pod2test. Read the
Test::Inline::Tutoral, really.

A test is denoted using either "=for testing" or a
"=begin/end testing" block.

=item B<is_pirate>

@pirates = is_pirate(@arrrgs);

Go through @arrrgs and return a list of pirates.

=begin testing

my @p = is_pirate('Blargbeard', 'Alfonse', 'Capt.

Hampton', 'Wesley');
ok(@p == 2);

=end testing

=cut

sub is_pirate {

....

}

Code Examples

Code examples in documentation are rarely tested.
Pod::Tests provides a way to do some testing of your exam
ples without repeating them.

A code example is denoted using "=for example begin" and
"=for example end".

=for example begin

use LWP::Simple;
getprint "http://www.goats.com";

=for example end

The code between the begin and end will be displayed as
documentation. So it will show up in perldoc. It will be
tested to ensure it compiles.

Using a normal "=for example" or "=begin/end example"
block lets you add code to your example that won't get
displayed. This is nice when you only want to show a code
fragment, yet still want to ensure things work.

=for example
sub mygrep (&@) { }

=for example begin

mygrep { $_ eq 'bar' } @stuff

=for example end

The mygrep() call would be a syntax error were the routine not declared with the proper prototype. Both pieces will
be considered part of the same example for the purposes of
testing, but will only display the "mygrep {...}" line.
You can also put "=for example" blocks afterwards.

Normally, an example will only be checked to see if it
compiles. If you put a "=for example_testing" afterwards,
more through checking will be done:

=for example begin

my $result = 2 + 2;

=for example end

=for example_testing

is( $result, 4, 'addition works' );

It will work like any other embedded test. In this case
the code will actually be run.

Finally, since many examples print their output, we trap
that into $_STDOUT_ and $_STDERR_ variables to capture
prints and warnings.

=for example begin

print "Hello, world!0;
warn "Beware the Ides of March!0;

=for example end

=for example_testing

ok( $_STDOUT_ eq "Hello, world!0 );
ok( $_STDERR_ eq "Beware the Ides of March!0 );

$_STDOUT_ and $_STDERR are cleared between testing blocks.

Formatting

The code examples and embedded tests are not translated
from POD, thus all the C<> and B<> style escapes are not
valid. Its literal Perl code.

Helpful Variables

Your test will have available to it several helpful vari
ables.

$Original_File

The location of the original file which pod2test was
run over, relative to where pod2test was run.

NOTES

Test::Inline has been tested and works on perl back to
5.004.

AUTHOR

Michael G Schwern <schwern@pobox.com>

SEE ALSO

Test::Inline::Tutorial, pod2test

perl v5.8.0 2002-04-11 Test::Inline(3)