Test::Pod::Snippets - Generate tests from pod code snippets
use Test::Pod::Snippets; my $tps = Test::Pod::Snippets->new(); $tps->generate_snippets( @pm_and_pod_files );
In a perfect world, a module's full API should be covered by an extensive battery of testcases neatly tucked in the distribution's t/ directory. But then, in a perfect world each backyard would have a marshmallow tree and postmen would consider their duty to circle all the real good deals in pamphlets before stuffing them in your mailbox. Obviously, we're not living in a perfect world.
t/
Typos and minor errors in module documentation. Let's face it: it happens to everyone. And while it's never the end of the world and is prone to rectify itself in time, it's always kind of embarassing. A little bit like electronic zits on prepubescent docs, if you will.
Test::Pod::Snippets's goal is to address those issues. Quite simply, it extracts verbatim text off pod documents -- which it assumes to be code snippets -- and generate test files out of them.
If you are using Module::Build, add the following to your Build.PL:
my $builder = Module::Build->new( # ... your M::B parameters PL_files => { 'script/test-pod-snippets.PL' => q{} }, add_to_cleanup => [ 't/pod-snippets-*.t' ], );
Then create the file script/test-pod-snippets.PL, which should contains
use Test::Pod::Snippets; my $tps = Test::Pod::Snippets->new; $tps->generate_snippets( qw# lib/your/module.pm lib/your/documentation.pod #);
And you're set! Running Build should now generate one test file for each given module.
If you prefer to generate the tests yourself, skip the modifications to Build.PL and call test-pod-snippets.PL from the distribution's main directory.
By default, Test::Pod::Snippets considers all verbatim pod text to be code snippets. To tell T::P::S to ignore subsequent pieces of verbatim text, add a =for test ignore to the pod. Likely, to return to the normal behavior, insert =for test. For example:
=for test ignore
=for test
A sure way to make your script die is to do: =for test ignore $y = 0; $x = 1/$y; The right (or safe) way to do it is rather: =for test $y = 0; $x = eval { 1/$y }; warn $@ if $@;
=for test and =begin test ... =end test can also be used to add code that should be include in the tests but not in the documentation.
=begin test ... =end test
Example:
The right way to do it is: $y = 0; $x = eval { 1/$y }; =for test # make sure an error happened is $x => undef; ok length($@), 'error is reported';
$tps = Test::Pod::Snippets->new
Creates a new Test::Pod::Snippets object.
$tps->generate_snippets( @source_files )
For each file in @source_files, extracts the code snippets from the pod found within and create the test file t/code-snippets-xx.t.
$test_script = $tps->extract_snippets( $file )
Returns the code of a test script containing the code snippets found in $file.
Yanick Champoux, <cpan at babyl.dyndns.org>
<cpan at babyl.dyndns.org>
Please report any bugs or feature requests to bug-test-pod-snippets at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Pod-Snippets. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-test-pod-snippets at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Test::Pod::Snippets
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Test-Pod-Snippets
CPAN Ratings
http://cpanratings.perl.org/d/Test-Pod-Snippets
RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Pod-Snippets
Search CPAN
http://search.cpan.org/dist/Test-Pod-Snippets
Copyright 2006 Yanick Champoux, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install Test::Pod::Snippets, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Test::Pod::Snippets
CPAN shell
perl -MCPAN -e shell install Test::Pod::Snippets
For more information on module installation, please visit the detailed CPAN module installation guide.