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
   independant 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 independantly 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 prefered 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 <[email protected]>

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

COPYRIGHT
   Copyright 2004 - 2009 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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.