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, <yanick at cpan.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:

• 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

SEE ALSO

Adam Kennedy's Test::Inline. Whereas Test::Pod::Snippets extracts tests out of the modules' documentation, Test::Inline allows to insert tests within a module, side-by-side with its code and documentation.

For example, the following code using Test::Pod::Snippets

    =head2 shout()

    Shoutify the passed string.

        # set $x to 'CAN YOU HEAR ME NOW?'
        my $x = shout( 'can you hear me now?' );

        =for test
        is $x => 'CAN YOU HEAR ME NOW?';

is equivalent to this code, using Test::Inline:

    =head2 shout()

    Shoutify the passed string.

        # set $x to 'CAN YOU HEAR ME NOW?'
        my $x = shout( 'can you hear me now?' );

    =begin testing
    my $x = shout( 'can you hear me now?' );
    is $x => 'CAN YOU HEAR ME NOW?';
    =end testing

COPYRIGHT & LICENSE

Copyright 2006, 2007 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.

cpanm Test::Pod::Snippets

perl -MCPAN -e shell
install Test::Pod::Snippets