1Test::Inline::Section(3U)ser Contributed Perl DocumentatiToenst::Inline::Section(3)
2
3
4

NAME

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

DESCRIPTION

9       This class implements a single section of tests. That is, a section of
10       POD beginning with "=begin test" or "=begin testing".
11
12   Types of Sections
13       There are two types of code sections. The first, beginning with "=begin
14       testing ...", contains a set of tests and other code to be executed at
15       any time (within a set of specifyable constraints). The second,
16       labelled "=begin testing SETUP", contains code to be executed at the
17       beginning of the test script, before any of the other sections are
18       executed. This allows any needed variables or environment to be set up
19       before the tests are run.  You can have more than one setup section,
20       and they will be written to the test file in order of appearance.
21
22   Test Section Header Syntax
23       Some examples of the different types of test headers are as follows.
24
25         # Normal anonymous test
26         =begin testing
27
28         ok( $foo == $bar, 'This is a test' );
29
30         =end testing
31
32         # A named test. Also provides the number of tests to run.
33         # Any test section can specify the number of tests.
34         =begin testing my_method 1
35
36         ok( $foo->my_method, '->my_method returns true' );
37
38         =end testing
39
40         # A named test with pre-requisites.
41         # Note that ONLY named tests can have pre-requisites
42         =begin testing this after my_method foo bar other_method Other::Class
43
44         ok( $foo->this, '->this returns true' );
45
46         =end testing
47
48       The first example shows a normal anonymous test. All anonymous test
49       sections are considered low priority, and we be run, in order of
50       appearance, AFTER all named tests have been run.
51
52       Any and all arguments used after "testing" must be in the form of
53       simple space seperated words. The first word is considered the "name"
54       of the test.  The intended use for these is generally to create one
55       named test section for each function or method, but you can name them
56       as you please. Test names must be unique, and are case sensitive.
57
58       After the name, you can provide the word "after" and provide a list of
59       other named tests that must be completed first in order to run this
60       test. This is provided so that when errors are encounted, they are
61       probably the result of this method or set of tests, and not in some
62       other method that this one relies on. It makes debugging a lot easier.
63       The word after is only a keyword when after the test name, so you can
64       use a test name of after as well.  The following are both legal
65
66         =begin testing after after that
67         =begin testing this after after
68
69       The easiest and recommended way of labeling the tests is simple to name
70       all tests after their methods, and put as a pre-requisite any other
71       methods that the method you are testing calls. Test::Inline will take
72       care of writing the tests to the test script in the correct order.
73       Please note you can NOT define circular relationships in the
74       prerequisites, or an error will occur.
75
76       If a number is provided as the last value, it will be taken to mean the
77       number of actual tests that will occur during the test section. While
78       preparing to write the test files, the processor will try to use these
79       to try to determine the number of files to write. If ALL test sections
80       to be written to a particular file have a test count, then the script
81       will use the total of these as a basic for providing Test::More with a
82       plan.
83
84       If ANY test sections to be written to a file do not have a test count,
85       the test file with use "no_plan".
86
87       Finally, Test::Inline will try to be forgiving in it's parsing of the
88       tests.  any missing prerequisites will be ignored. Also, as long as it
89       does not break a prerequisite, all named tests will be attempted to be
90       run in their order of appearance.
91

METHODS

93   new
94         my $Section = Test::Inline::Section->new( $pod );
95
96       The "new" constructor takes a string of POD, which must be a single
97       section of relevant pod ( preferably produced by
98       Test::Inline::ExtractHandler ), and creates a new section object for
99       it.
100
101       Returns a new "Test::Inline::Section" object if passed POD in the form
102       "=begin testing ...". Returns "undef" on error.
103
104   parse
105         my $SectionList = Test::Inline::Section( @elements );
106
107       Since version 1.50 Test::Inline has been extracting package statements
108       so that as the sections are extracted, we can determine which sections
109       belong to which packages, and seperate them accordingly.
110
111       The "parse" method takes all of the elements from a file, and returns
112       all of the Sections. By doing it here, we can track the package context
113       and set it in the Sections.
114
115   setup
116         my $run_first = $Section->setup;
117
118       The "setup" accessor indicates that this section is a "setup" section,
119       to be run at the beginning of the generated test script.
120
121       Returns true if this is a setup section, false otherwise.
122
123   example
124         my $just_compile = $Section->example;
125
126       The "example" accessor indicates that this section is an "example"
127       section, to be compile-tested instead of run.
128
129       Returns true if this is an example section, false otherwise.
130
131   context
132       The "context" method returns the package context of the unit test
133       section, or false if the unit test section appeared out of context.
134
135   name
136       The "name" method returns the name of the test section, or false if the
137       test if anonymous.
138
139   tests
140       The "tests" method returns the number of Test::Builder-compatible tests
141       that will run within the test section. Returns "undef" if the number of
142       tests is unknown.
143
144   begin
145       For use mainly in debugging, the "begin" method returns the literal
146       string of the begin line/paragraph.
147
148   anonymous
149         my $is_anonymous = $Section->anonymous;
150
151       The "anonymous" method returns true if the test section is an unnamed
152       anonymous section, or false if it is a named section or a setup
153       section.
154
155   after
156         my @names = $Section->after;
157
158       The "after" method returns the list of other named tests that this test
159       section says it should be run after.
160
161       Returns a list of test name, or the null list "()" if the test does not
162       have to run after any other named tests.
163
164   classes
165         my @classes = $Section->classes;
166
167       The "classes" method returns the list of test classes that the test
168       depends on, and should be run before the tests. These values are used
169       to determine the set of class-level dependencies for the entire test
170       file.
171
172       Returns a list of class names, or the null list "()" if the test does
173       not have any class-level dependencies.
174
175   content
176         my $code = $Section->content;
177
178       The "content" method returns the actual testing code contents of the
179       section, with the leading "=begin" and trailing "=end" removed.
180
181       Returns a string containing the code, or the null string "" if the
182       section was empty.
183

SUPPORT

185       See the main SUPPORT section.
186

AUTHOR

188       Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
189
191       Copyright 2004 - 2009 Adam Kennedy.
192
193       This program is free software; you can redistribute it and/or modify it
194       under the same terms as Perl itself.
195
196       The full text of the license can be found in the LICENSE file included
197       with this module.
198
199
200
201perl v5.12.0                      2009-07-14          Test::Inline::Section(3)
Impressum