1Test::Inline::Section(3U)ser Contributed Perl DocumentatiToenst::Inline::Section(3)
2
6 Test::Inline::Section - Implements a section of tests
7
9 This class implements a single section of tests. That is, a section of
10 POD beginning with "=begin test" or "=begin testing".
11 Types of Sections
13 There are two types of code sections. The first, beginning with "=begin
15 testing ...", contains a set of tests and other code to be executed at
16 any time (within a set of specifyable constraints). The second,
17 labelled "=begin testing SETUP", contains code to be executed at the
18 beginning of the test script, before any of the other sections are exe‐
19 cuted. This allows any needed variables or environment to be set up
20 before the tests are run. You can have more than one setup section,
21 and they will be written to the test file in order of appearance.
22 Test Section Header Syntax
24 Some examples of the different types of test headers are as follows.
26 # Normal anonymous test
28 =begin testing
29 ok( $foo == $bar, 'This is a test' );
31 =end testing
33 # A named test. Also provides the number of tests to run.
35 # Any test section can specify the number of tests.
36 =begin testing my_method 1
37 ok( $foo->my_method, '->my_method returns true' );
39 =end testing
41 # A named test with pre-requisites.
43 # Note that ONLY named tests can have pre-requisites
44 =begin testing this after my_method foo bar other_method Other::Class
45 ok( $foo->this, '->this returns true' );
47 =end testing
49 The first example shows a normal anonymous test. All anonymous test
51 sections are considered low priority, and we be run, in order of
52 appearance, AFTER all named tests have been run.
53 Any and all arguments used after "testing" must be in the form of sim‐
55 ple space seperated words. The first word is considered the "name" of
56 the test. The intended use for these is generally to create one named
57 test section for each function or method, but you can name them as you
58 please. Test names must be unique, and are case sensitive.
59 After the name, you can provide the word "after" and provide a list of
61 other named tests that must be completed first in order to run this
62 test. This is provided so that when errors are encounted, they are
63 probably the result of this method or set of tests, and not in some
64 other method that this one relies on. It makes debugging a lot easier.
65 The word after is only a keyword when after the test name, so you can
66 use a test name of after as well. The following are both legal
67 =begin testing after after that
69 =begin testing this after after
70 The easiest and recommended way of labeling the tests is simple to name
72 all tests after their methods, and put as a pre-requisite any other
73 methods that the method you are testing calls. Test::Inline will take
74 care of writing the tests to the test script in the correct order.
75 Please note you can NOT define circular relationships in the prerequi‐
76 sites, or an error will occur.
77 If a number is provided as the last value, it will be taken to mean the
79 number of actual tests that will occur during the test section. While
80 preparing to write the test files, the processor will try to use these
81 to try to determine the number of files to write. If ALL test sections
82 to be written to a particular file have a test count, then the script
83 will use the total of these as a basic for providing Test::More with a
84 plan.
85 If ANY test sections to be written to a file do not have a test count,
87 the test file with use "no_plan".
88 Finally, Test::Inline will try to be forgiving in it's parsing of the
90 tests. any missing prerequisites will be ignored. Also, as long as it
91 does not break a prerequisite, all named tests will be attempted to be
92 run in their order of appearance.
93
95 new
96 my $Section = Test::Inline::Section->new( $pod );
98 The "new" constructor takes a string of POD, which must be a single
100 section of relevant pod ( preferably produced by Test::Inline::Extrac‐
101 tHandler ), and creates a new section object for it.
102 Returns a new "Test::Inline::Section" object if passed POD in the form
104 "=begin testing ...". Returns "undef" on error.
105 parse
107 my $SectionList = Test::Inline::Section( @elements );
109 Since version 1.50 Test::Inline has been extracting package statements
111 so that as the sections are extracted, we can determine which sections
112 belong to which packages, and seperate them accordingly.
113 The "parse" method takes all of the elements from a file, and returns
115 all of the Sections. By doing it here, we can track the package context
116 and set it in the Sections.
117 setup
119 my $run_first = $Section->setup;
121 The "setup" accessor indicates that this section is a "setup" section,
123 to be run at the beginning of the generated test script.
124 Returns true if this is a setup section, false otherwise.
126 example
128 my $just_compile = $Section->example;
130 The "example" accessor indicates that this section is an "example" sec‐
132 tion, to be compile-tested instead of run.
133 Returns true if this is an example section, false otherwise.
135 context
137 The "context" method returns the package context of the unit test sec‐
139 tion, or false if the unit test section appeared out of context.
140 name
142 The "name" method returns the name of the test section, or false if the
144 test if anonymous.
145 tests
147 The "tests" method returns the number of Test::Builder-compatible tests
149 that will run within the test section. Returns "undef" if the number of
150 tests is unknown.
151 begin
153 For use mainly in debugging, the "begin" method returns the literal
155 string of the begin line/paragraph.
156 anonymous
158 my $is_anonymous = $Section->anonymous;
160 The "anonymous" method returns true if the test section is an unnamed
162 anonymous section, or false if it is a named section or a setup sec‐
163 tion.
164 after
166 my @names = $Section->after;
168 The "after" method returns the list of other named tests that this test
170 section says it should be run after.
171 Returns a list of test name, or the null list "()" if the test does not
173 have to run after any other named tests.
174 classes
176 my @classes = $Section->classes;
178 The "classes" method returns the list of test classes that the test
180 depends on, and should be run before the tests. These values are used
181 to determine the set of class-level dependencies for the entire test
182 file.
183 Returns a list of class names, or the null list "()" if the test does
185 not have any class-level dependencies.
186 content
188 my $code = $Section->content;
190 The "content" method returns the actual testing code contents of the
192 section, with the leading "=begin" and trailing "=end" removed.
193 Returns a string containing the code, or the null string "" if the sec‐
195 tion was empty.
196
198 See the main SUPPORT section.
199
201 Adam Kennedy <adamk@cpan.org>, <http://ali.as/>
202
204 Copyright 2004 - 2007 Adam Kennedy.
205 This program is free software; you can redistribute it and/or modify it
207 under the same terms as Perl itself.
208 The full text of the license can be found in the LICENSE file included
210 with this module.
211perl v5.8.8 2007-08-17 Test::Inline::Section(3)