/ 
Test-Pod-Snippets-0.01
River stage zero No dependents
/ Test::Pod::Snippets

NAME

Test::Pod::Snippets - Generate tests from pod code snippets

SYNOPSIS

use Test::Pod::Snippets;

my $tps = Test::Pod::Snippets->new();
$tps->generate_snippets( @pm_and_pod_files );

DESCRIPTION

Fact 1

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.

Fact 2

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.

HOW TO USE TEST::POD::SNIPPETS IN YOUR DISTRIBUTION

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.

SYNTAX

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:

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.

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';

METHODS

new

$tps = Test::Pod::Snippets->new

Creates a new Test::Pod::Snippets object.

generate_snippets

$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.

extract_snippets

$test_script = $tps->extract_snippets( $file )

Returns the code of a test script containing the code snippets found in $file.

AUTHOR

Yanick Champoux, <cpan at babyl.dyndns.org>

BUGS

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.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Test::Pod::Snippets

You can also look for information at:

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

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.