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

VERSION
    version 0.07

SYNOPSIS
        use Test::More tests => 3;

        use Test::Pod::Snippets;

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

        my @modules = qw/ Foo Foo::Bar Foo::Baz /;

        $tps->runtest( module => $_, testgroup => 1 ) for @modules;

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.

METHODS
  new( %options )
    Creates a new Test::Pod::Snippets object. The method accepts the
    following options:

    verbatim => *$boolean*
        If set to true, incorporates the pod's verbatim parts to the test.

        Set to true by default.

    functions => *$boolean*
        If set to true, extracts function definitions from the pod. More
        specifically, Test::Pod::Snippets looks for a pod section called
        FUNCTIONS, and assumes the title of all its subsections to be
        functions.

        For example, the pod

            =head1 FUNCTIONS

            =head2 play_song( I<$artist>, I<$song_title> )

            Play $song_title from $artist.

            =head2 set_lighting( I<$intensity> )

            Set the room's light intensity (0 is pitch black 
            and 1 is supernova white, -1 triggers the stroboscope).

        would generate the code

            @result = play_song( $artist, $song_title );
            @result = set_lightning( $intensity );

        Pod markups are automatically stripped from the headers.

    methods => *$boolean*
        Same as "functions", but with methods. In this case,
        Test::Pod::Snippets looks for a pod section called METHODS. The
        object used for the tests is assumed to be '$thingy' (but can be
        overriden using the argument "object_name", and its class must be
        given by a variable '$class'.

        For example, the pod

            =head1 METHODS

            =for test
                $class = 'Amphibian::Frog';

            =head2 new( $name )

            Create a new froggy!

            =head2 jump( $how_far )

            Make it jumps.

        will produces

            $class = 'Amphibian::Frog';
            $thingy = $class->new( $name );
            @result = $thingy->jump( $how_far );

    object_name => *$identifier*
        The name of the object (with the leading '$') to be used for the
        methods if the T:P:S object is set to extract methods.

    preserve_lines => *$boolean*
        If sets to true (which is the default), the generated code will be
        peppered with '#line' pre-compiler lines that will have any failing
        test point to the test's original file.

  is_extracting_verbatim
  is_extracting_functions
  is_extracting_methods
    Returns true if the object is configured to extract that part of the
    pod, false otherwise.

  extracts_verbatim( *$boolean* )
  extracts_functions( *$boolean* )
  extracts_methods( *$boolean* )
    Configure the object to extract (or not) the given pod parts.

  generate_test( $input_type => *$input*, %options )
    Extracts the pod off *$input* and generate tests out of it.
    *$input_type* can be 'file' (a filename), 'fh' (a filehandler), 'pod' (a
    string containing pod) or 'module' (a module name).

    The method returns the generate tests as a string.

    The method accepts the following options:

    standalone => *$boolean*
        If standalone is true, the generated code will be a self-sufficient
        test script. Defaults to 'false'.

            # create a test script out of the module Foo::Bar
            open my $test_fh, '>', 't/foo-bar.t' or die;
            print {$test_fh} $tps->generate_test( 
                module     => 'Foo::Bar',
                standalone => 1 ,
            );

    sanity_tests => *$boolean*
        If true (which is the default), two tests are added to the very
        beginning and end of the extracted code, like so:

            ok 1 => 'the tests compile';   
            $extracted_code
            ok 1 => 'we reached the end!';

    testgroup => *$boolean*
        If true, the extracted code will be wrapped in a Test::Group test,
        which will report a single 'ok' for the whole series of test (but
        will give more details if something goes wrong). Is set to 'false'
        by default.

  generate_test_file( $input_type => *$input*, %options )
    Does the same as "generate_test", but save the generated code in a file.
    The name of the file is the value of the option output, if given. If the
    file already exist, the method dies. If output is not given, the
    filename will be of the format 'tps-XXXX.t', where XXXX is choosen not
    to interfere with existing tests. Exception made of "output", the
    options accepted by the method are the same than for "generate_test".

    Returns the name of the created file.

  runtest( $input_type => *$input*, %options )
    Does the same than "generate_test", except that it executes the
    generated code rather than return it. The arguments are treated the same
    as for "generate_test".

  generate_snippets( @filenames )
    For each file in *@filenames*, generates a *pod-snippets-X.t* file in
    the "t/" directory.

  extract_snippets_from_file( $filename )
    Extracts the snippets from the file and returns a string containing the
    generated tests.

  extract_snippets( $pod )
    Extracts the snippets from the string *$pod* and returns a string
    containing the generated tests.

  snippets_ok( $pod )
    Extracts the snippets from *$pod* (which can be a string or a filename)
    and run the code, returning b<true> if the code run and b<false> if it
    fails.

HOW TO USE TEST::POD::SNIPPETS IN YOUR DISTRIBUTION
    The easiest way is to create a test.t file calling Test::Pod::Snippets
    as shown in the synopsis. If, however, you don't want to add T:P:S to
    your module's dependencies, you can 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/tps-*.t' ],
      );

    Then create the file script/test-pod-snippets.PL, which should contains

        use Test::Pod::Snippets;

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

        my @files = qw#
            lib/your/module.pm
            lib/your/documentation.pod
        #;
    
        print "generating tps tests...\n";
        print $tps->generate_test_file( $_ ), "created\n" for @files;
        print "done\n";

    And you're set! Running Build should now generate one test file for each
    given file.

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

SEE ALSO
    podsnippets

  Test::Inline
    Whereas Test::Pod::Snippets extracts tests out of the modules'
    documentation, Adam Kennedy's *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

AUTHOR
    Yanick Champoux <yanick@cpan.org>

COPYRIGHT AND LICENSE
    This software is copyright (c) 2006 by Yanick Champoux.

    This is free software; you can redistribute it and/or modify it under
    the same terms as the Perl 5 programming language system itself.