NAME
    Test::Inline - Inlining your tests next to the code being tested

DESCRIPTION
    Embedding tests allows tests to be placed near the code its testing.
    This is a nice supplement to the traditional .t files.

    It's like XUnit, Perl-style.

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

      # A fragment of general test code
  
      =begin testing
  
      ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
  
      =end testing

      # Completely test a single method
  
      =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 conceptually
    indepdendant of each other. Each chunk of testing code should not die or
    crash if it is run before or after another chunk.

    Using "pod2test" or another test compiler, you can then transform these
    chunks in one file, or an entire tree of modules, into a one or more
    standard Test::More-based test scripts.

    These test scripts can be executed as normal.

  What is Test::Inline good for?
    Firstly, 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 in fact, and the next time the test
    compiler is run, a test script will just appear.

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

    That is, any code which can be independantly tested from external
    dependencies such as databases, and that has no side-effects on external
    systems.

    All of this code, written by multiple people, can be checked for
    internal consistency, you can check it's API, anything you like, in
    great detail.

  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 do with it.

    *   Static testing across the entire codebase

    *   Functional testing

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

  Getting Started
        ... to be completed

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

        The "new" constructor creates a new 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 generated test files, but listed
            in the 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 customer
            OutputHandler, the value of output refers to the location within
            the OutputHandler the files will be written to.

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

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

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

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

  add $file, \$source
        The "add" method takes as argument a filename or a reference to a
        SCALAR containing perl code, parses it, and creates 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.

  classes
        The "classes" method returns a list of the names of all the classes
        that have been added to the 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 Inline object. Returns
        "undef" if the class has not been added to the 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 content 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 test directory.

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

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>

        Contacts regarding professional support, assistance, or
        customisations for large scale uses of Test::Inline is available
        from <http://phase-n.com/>.

        For other issues, contact the maintainer.

AUTHOR
        Adam Kennedy (Maintainer), <http://ali.as/>, cpan@ali.as

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

COPYRIGHT
        Copyright (c) 2004 - 2005 Phase N Austalia. All rights reserved.

        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.

