NAME

       Test::Inline::Section - Implements a section of tests

VERSION

       version 2.214

DESCRIPTION

       This class implements a single section of tests. That is, a section of POD beginning with
       "=begin test" or "=begin testing".

   Types of Sections
       There are two types of code sections. The first, beginning with "=begin testing ...",
       contains a set of tests and other code to be executed at any time (within a set of
       specifyable constraints). The second, labelled "=begin testing SETUP", contains code to be
       executed at the beginning of the test script, before any of the other sections are
       executed. This allows any needed variables or environment to be set up before the tests
       are run.  You can have more than one setup section, and they will be written to the test
       file in order of appearance.

   Test Section Header Syntax
       Some examples of the different types of test headers are as follows.

         # Normal anonymous test
         =begin testing

         ok( $foo == $bar, 'This is a test' );

         =end testing

         # A named test. Also provides the number of tests to run.
         # Any test section can specify the number of tests.
         =begin testing my_method 1

         ok( $foo->my_method, '->my_method returns true' );

         =end testing

         # A named test with pre-requisites.
         # Note that ONLY named tests can have pre-requisites
         =begin testing this after my_method foo bar other_method Other::Class

         ok( $foo->this, '->this returns true' );

         =end testing

       The first example shows a normal anonymous test. All anonymous test sections are
       considered low priority, and we be run, in order of appearance, AFTER all named tests have
       been run.

       Any and all arguments used after "testing" must be in the form of simple space separated
       words. The first word is considered the "name" of the test.  The intended use for these is
       generally to create one named test section for each function or method, but you can name
       them as you please. Test names must be unique, and are case sensitive.

       After the name, you can provide the word "after" and provide a list of other named tests
       that must be completed first in order to run this test. This is provided so that when
       errors are encounted, they are probably the result of this method or set of tests, and not
       in some other method that this one relies on. It makes debugging a lot easier. The word
       after is only a keyword when after the test name, so you can use a test name of after as
       well.  The following are both legal

         =begin testing after after that
         =begin testing this after after

       The easiest and recommended way of labeling the tests is simple to name all tests after
       their methods, and put as a pre-requisite any other methods that the method you are
       testing calls. Test::Inline will take care of writing the tests to the test script in the
       correct order. Please note you can NOT define circular relationships in the prerequisites,
       or an error will occur.

       If a number is provided as the last value, it will be taken to mean the number of actual
       tests that will occur during the test section. While preparing to write the test files,
       the processor will try to use these to try to determine the number of files to write. If
       ALL test sections to be written to a particular file have a test count, then the script
       will use the total of these as a basic for providing Test::More with a plan.

       If ANY test sections to be written to a file do not have a test count, the test file with
       use "no_plan".

       Finally, Test::Inline will try to be forgiving in it's parsing of the tests.  any missing
       prerequisites will be ignored. Also, as long as it does not break a prerequisite, all
       named tests will be attempted to be run in their order of appearance.

METHODS

   new
         my $Section = Test::Inline::Section->new( $pod );

       The "new" constructor takes a string of POD, which must be a single section of relevant
       pod ( preferably produced by Test::Inline::ExtractHandler ), and creates a new section
       object for it.

       Returns a new "Test::Inline::Section" object if passed POD in the form "=begin testing
       ...". Returns "undef" on error.

   parse
         my $SectionList = Test::Inline::Section( @elements );

       Since version 1.50 Test::Inline has been extracting package statements so that as the
       sections are extracted, we can determine which sections belong to which packages, and
       separate them accordingly.

       The "parse" method takes all of the elements from a file, and returns all of the Sections.
       By doing it here, we can track the package context and set it in the Sections.

   setup
         my $run_first = $Section->setup;

       The "setup" accessor indicates that this section is a "setup" section, to be run at the
       beginning of the generated test script.

       Returns true if this is a setup section, false otherwise.

   example
         my $just_compile = $Section->example;

       The "example" accessor indicates that this section is an "example" section, to be compile-
       tested instead of run.

       Returns true if this is an example section, false otherwise.

   context
       The "context" method returns the package context of the unit test section, or false if the
       unit test section appeared out of context.

   name
       The "name" method returns the name of the test section, or false if the test if anonymous.

   tests
       The "tests" method returns the number of Test::Builder-compatible tests that will run
       within the test section. Returns "undef" if the number of tests is unknown.

   begin
       For use mainly in debugging, the "begin" method returns the literal string of the begin
       line/paragraph.

   anonymous
         my $is_anonymous = $Section->anonymous;

       The "anonymous" method returns true if the test section is an unnamed anonymous section,
       or false if it is a named section or a setup section.

   after
         my @names = $Section->after;

       The "after" method returns the list of other named tests that this test section says it
       should be run after.

       Returns a list of test name, or the null list "()" if the test does not have to run after
       any other named tests.

   classes
         my @classes = $Section->classes;

       The "classes" method returns the list of test classes that the test depends on, and should
       be run before the tests. These values are used to determine the set of class-level
       dependencies for the entire test file.

       Returns a list of class names, or the null list "()" if the test does not have any class-
       level dependencies.

   content
         my $code = $Section->content;

       The "content" method returns the actual testing code contents of the section, with the
       leading "=begin" and trailing "=end" removed.

       Returns a string containing the code, or the null string "" if the section was empty.

SUPPORT

       See the main SUPPORT section.

       Bugs may be submitted through the RT bug tracker
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Inline> (or
       bug-Test-Inline@rt.cpan.org <mailto:bug-Test-Inline@rt.cpan.org>).

AUTHOR

       Adam Kennedy <adamk@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2003 by Adam Kennedy.

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