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

VERSION

9       version 2.214
10

DESCRIPTION

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

METHODS

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

SUPPORT

188       See the main SUPPORT section.
189
190       Bugs may be submitted through the RT bug tracker
191       <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Inline> (or
192       bug-Test-Inline@rt.cpan.org <mailto:bug-Test-Inline@rt.cpan.org>).
193

AUTHOR

195       Adam Kennedy <adamk@cpan.org>
196
198       This software is copyright (c) 2003 by Adam Kennedy.
199
200       This is free software; you can redistribute it and/or modify it under
201       the same terms as the Perl 5 programming language system itself.
202
203
204
205perl v5.36.0                      2023-01-20          Test::Inline::Section(3)
Impressum