Provided by: libtest-inline-perl_2.213-1_all bug

NAME

       Test::Inline - Embed your tests in your code, next to what is being tested

DESCRIPTION

       Embedding tests allows tests to be placed near the code being tested.

       This is a nice supplement to the traditional .t files.

   How does it work?
       "Test::Inline" lets you write small fragments of general or function-specific testing
       code, and insert it anywhere you want in your modules, inside a specific tagged POD
       segment, like the following.

         =begin testing

         # This code assumes we have a cpuinfo file
         ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );

         =end testing

         =begin testing label

         # Test generation of the <label> HTML tag
         is( My::HTML->label('foo'),        '<label>foo</label>',           '->label(simple) works' );
         is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works'    );

         =end testing

       You can add as many, or as few, of these chunks of tests as you wish.  The key condition
       when writing them is that they should be logically independent of each other. Each chunk
       of testing code should not die or crash if it is run before or after another chunk.

       Using inline2test or another test compiler, you can then transform these chunks in a test
       script, or an entire tree of modules into a complete set of standard Test::More-based test
       scripts.

       These test scripts can then be executed as normal.

   What is Test::Inline good for?
       "Test::Inline" is incredibly useful for doing ad-hoc unit testing.

       In any large groups of modules, you can add testing code here, there and everywhere,
       anywhere you want. The next time the test compiler is run, a new test script will just
       appear.

       This also makes it great for testing assumptions you normally wouldn't bother to write
       run-time code to test. It ensures that your assumptions about the way Perl does some
       operation, or about the state of the host, are confirmed at install-time.

       If your assumption is ever wrong, it gets picked up at install-time and based on the test
       failures, you can correct your assumption.

       It's also extremely useful for systematically testing self-contained code.

       That is, any code which can be independent tested without the need for external systems
       such as databases, and that has no side-effects on external systems.

       All of this code, written by multiple people, can then have one single set of test files
       generated. You can check all the bits and pieces of a large API, or anything you like, in
       fine detail.

       Test::Inline also introduces the concept of unit-tested documentation.

       Not only can your code be tested, but if you have a FAQ or some other pure documentation
       module, you can validate that the documentation is correct for the version of the module
       installed.

       If the module ever changes to break the documentation, you can catch it and correct the
       documentation.

   What is Test::Inline bad for?
       "Test::Inline" is not a complete testing solution, and there are several types of testing
       you probably DON'T want to use it for.

       •   Static testing across the entire codebase

       •   Functional testing

       •   Tests with side-effects such as those that might change a testing database

   Getting Started
       Because Test::Inline creates test scripts with file names that don't start with a number
       (for ordering purposes), the first step is to create your normal test scripts using file
       names in the CPAN style of 01_compile.t, 02_main.t, 03_foobar.t, and so on.

       You can then add your testing fragments wherever you like throughout your code, and use
       the inline2test script to generate the test scripts for the inline tests. By default the
       test scripts will be named after the packages/classes that the test fragments are found
       in.

       Tests for Class::Name will end up in the file "class_name.t".

       These test files sit quite happily alongside your number test scripts.

       When you run the test suite as you normally would, the inline scripts will be run after
       the numbered tests.

METHODS

   new
         my $Tests = Test::Inline->new(
             verbose  => 1,
             readonly => 1,
             output   => 'auto',
             manifest => 'auto/manifest',
         );

       The "new" constructor creates a new test generation framework. Once the constructor has
       been used to create the generator, the "add_class" method can be used to specify classes,
       or class heirachies, to generate tests for.

       verbose - The "verbose" option causes the generator to write state and debugging
       information to STDOUT as it runs.

       manifest - The "manifest" option, if provided, will cause a manifest file to be created
       and written to disk. The manifest file contains a list of all the test files generated,
       but listed in the preferred order they should be processed to best satisfy the class-level
       dependency of the tests.

       check_count - The "check_count" value controls how strictly the test script will watch the
       number of tests that have been executed.

       When set to false, the script does no count checking other than the standard total count
       for scripts (where all section counts are known)

       When set to 1 (the default), "Test::Inline" does smart count checking, doing section-by-
       section checking for known-count sections only when the total for the entire script is not
       known.

       When set to 2 or higher, "Test::Inline" does full count checking, doing section-by-section
       checking for every section with a known number of tests.

       file_content - The "file_content" option should be provided as a CODE reference, which
       will be passed as arguments the "Test::Inline" object, and a single Test::Inline::Script
       object, and should return a string containing the contents of the resulting test file.
       This will be written to the "OutputHandler".

       output - The "output" option provides the location of the directory where the tests will
       be written to. It should both already exist, and be writable. If using a custom
       "OutputHandler", the value of "output" should refer to the location within the
       OutputHandler that the files will be written to.

       readonly - The "readonly" option, if provided, indicates that any generated test files
       should be created (or set when updated) with read-only permissions, to prevent
       accidentally adding to or editing the test scripts directly (instead of via the classes).

       This option is currently disabled by default, by may be enabled by default in a future
       release, so if you do NOT want your tests being created as read-only, you should
       explicitly set this option to false.

       InputHandler - The "InputHandler" option, if provided, supplies an alternative
       "FileHandler" from which source modules are retrieved.

       OuputHandler - The "OutputHandler" option, if provided, supplies an alternative
       "FileHandler" to which the resulting test scripts are written.

       Returns a new "Test::Inline" object on success.

       Returns "undef" if there is a problem with one of the options.

   exception
       The "exception" method returns a flag which indicates whether error will be returned via
       exceptions.

   InputHandler
       The "InputHandler" method returns the file handler object that will be used to find and
       load the source code.

   ExtractHandler
       The "ExtractHandler" accessor returns the object that will be used to extract the test
       sections from the source code.

   ContentHandler
       The "ContentHandler" accessor return the script content generation handler.

   OutputHandler
       The "OutputHandler" accessor returns the file handler object that the generated test
       scripts will be written to.

   add $file, $directory, \$source, $Handle
       The "add" method is a parameter-sensitive method for adding something to the build
       schedule.

       It takes as argument a file path, a directory path, a reference to a SCALAR containing
       perl code, or an IO::Handle (or subclass) object. It will retrieve code from the parameter
       as appropriate, parse it, and create zero or more Test::Inline::Script objects
       representing the test scripts that will be generated for that source code.

       Returns the number of test scripts added, which could be zero, or "undef" on error.

   add_class
         $Tests->add_class( 'Foo::Bar' );
         $Tests->add_class( 'Foo::Bar', recursive => 1 );

       The "add_class" method adds a class to the list of those to have their tests generated.
       Optionally, the "recursive" option can be provided to add not just the class you provide,
       but all classes below it as well.

       Returns the number of classes found with inline tests, and added, including 0 if no
       classes with tests are found. Returns "undef" if an error occurs while adding the class or
       it's children.

   add_all
       The "add_all" method will search the "InputHandler" for all *.pm files, and add them to
       the generation set.

       Returns the total number of test scripts added, which may be zero, or "undef" on error.

   classes
       The "classes" method returns a list of the names of all the classes that have been added
       to the "Test::Inline" object, or the null list "()" if nothing has been added.

   class
       For a given class name, fetches the Test::Inline::Script object for that class, if it has
       been added to the "Test::Inline" object. Returns "undef" if the class has not been added
       to the "Test::Inline" object.

   filenames
       For all of the classes added, the "filenames" method generates a map of the filenames that
       the test files for the various classes should be written to.

       Returns a reference to a hash with the classes as keys, and filenames as values.

       Returns 0 if there are no files to write.

       Returns "undef" on  error.

   schedule
       While the "filenames" method generates a map of the files for the various classes, the
       "schedule" returns the list of file names in the order in which they should actually be
       executed.

       Returns a reference to an array containing the file names as strings.

       Returns 0 if there are no files to write.

       Returns "undef" on error.

   manifest
       The "manifest" generates the contents of the manifest file, if it is both wanted and
       needed.

       Returns the contents of the manifest file as a normal string, false if it is either not
       wanted or needed, or "undef" on error.

   save
         $Tests->save;

       The "save" method generates the test files for all classes, and saves them to the "output"
       directory.

       Returns the number of test files generated. Returns "undef" on error.

BUGS

       The "Extended =begin" syntax used for non-trivial sections is not formalised as part of
       the POD spec yet, although it is on the track to being included.

       While simple '=begin testing' sections are fine and will pass POD testing, extended begin
       sections may cause POD errors.

TO DO

       - Add support for "example" sections

       - Add support for "=for" sections

SUPPORT

       Bugs should always be submitted via the CPAN bug tracker

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>

       Professional support, assistance, or customisations for large scale uses of "Test::Inline"
       are available from <http://phase-n.com/>.

       For other issues, contact the maintainer.

AUTHOR

       Adam Kennedy <adamk@cpan.org>

ACKNOWLEDGEMENTS

       Thank you to Phase N (<http://phase-n.com/>) for permitting the open sourcing and release
       of this distribution.

COPYRIGHT

       Copyright 2004 - 2013 Adam Kennedy.

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

       The full text of the license can be found in the LICENSE file included with this module.