Test::Inline::Section(User Contributed Perl DocumentatTest::Inline::Section(3)NAMETest::Inline::Section - Implements a section of tests
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 seperated 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 seperate 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.
AUTHOR
Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
COPYRIGHT
Copyright 2004 - 2010 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.
perl v5.14.1 2010-11-22 Test::Inline::Section(3)
