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 examples 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 endThe 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 endThe 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!\n";
warn "Beware the Ides of March!\n";
=for example end
=for example_testing
ok( $_STDOUT_ eq "Hello, world!\n" );
ok( $_STDERR_ eq "Beware the Ides of March!\n" );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.
NOTES
Test::Inline has been tested and works on perl back to 5.004.
AUTHOR
Michael G Schwern <schwern@pobox.com>