1Test::Inline(3) User Contributed Perl Documentation Test::Inline(3)
2
6 Test::Inline - Embed your tests in your code, next to what is being
7 tested
8
10 Embedding tests allows tests to be placed near the code being tested.
11 This is a nice supplement to the traditional .t files.
13 How does it work?
15 "Test::Inline" lets you write small fragments of general or function-
16 specific testing code, and insert it anywhere you want in your modules,
17 inside a specific tagged POD segment, like the following.
18 =begin testing
20 # This code assumes we have a cpuinfo file
22 ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
23 =end testing
25 =begin testing label
27 # Test generation of the <label> HTML tag
29 is( My::HTML->label('foo'), '<label>foo</label>', '->label(simple) works' );
30 is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works' );
31 =end testing
33 You can add as many, or as few, of these chunks of tests as you wish.
35 The key condition when writing them is that they should be logically
36 independant of each other. Each chunk of testing code should not die or
37 crash if it is run before or after another chunk.
38 Using inline2test or another test compiler, you can then transform
40 these chunks in a test script, or an entire tree of modules into a
41 complete set of standard Test::More-based test scripts.
42 These test scripts can then be executed as normal.
44 What is Test::Inline good for?
46 "Test::Inline" is incredibly useful for doing ad-hoc unit testing.
47 In any large groups of modules, you can add testing code here, there
49 and everywhere, anywhere you want. The next time the test compiler is
50 run, a new test script will just appear.
51 This also makes it great for testing assumptions you normally wouldn't
53 bother to write run-time code to test. It ensures that your assumptions
54 about the way Perl does some operation, or about the state of the host,
55 are confirmed at install-time.
56 If your assumption is ever wrong, it gets picked up at install-time and
58 based on the test failures, you can correct your assumption.
59 It's also extremely useful for systematically testing self-contained
61 code.
62 That is, any code which can be independantly tested without the need
64 for external systems such as databases, and that has no side-effects on
65 external systems.
66 All of this code, written by multiple people, can then have one single
68 set of test files generated. You can check all the bits and pieces of a
69 large API, or anything you like, in fine detail.
70 Test::Inline also introduces the concept of unit-tested documentation.
72 Not only can your code be tested, but if you have a FAQ or some other
74 pure documentation module, you can validate that the documentation is
75 correct for the version of the module installed.
76 If the module ever changes to break the documentation, you can catch it
78 and correct the documentation.
79 What is Test::Inline bad for?
81 "Test::Inline" is not a complete testing solution, and there are
82 several types of testing you probably DON'T want to use it for.
83 · Static testing across the entire codebase
85 · Functional testing
87 · Tests with side-effects such as those that might change a testing
89 database
90 Getting Started
92 Because Test::Inline creates test scripts with file names that don't
93 start with a number (for ordering purposes), the first step is to
94 create your normal test scripts using file names in the CPAN style of
95 01_compile.t, 02_main.t, 03_foobar.t, and so on.
96 You can then add your testing fragments wherever you like throughout
98 your code, and use the inline2test script to generate the test scripts
99 for the inline tests. By default the test scripts will be named after
100 the packages/classes that the test fragments are found in.
101 Tests for Class::Name will end up in the file "class_name.t".
103 These test files sit quite happily alongside your number test scripts.
105 When you run the test suite as you normally would, the inline scripts
107 will be run after the numbered tests.
108
110 new
111 my $Tests = Test::Inline->new(
112 verbose => 1,
113 readonly => 1,
114 output => 'auto',
115 manifest => 'auto/manifest',
116 );
117 The "new" constructor creates a new test generation framework. Once the
119 constructor has been used to create the generator, the "add_class"
120 method can be used to specify classes, or class heirachies, to generate
121 tests for.
122 verbose - The "verbose" option causes the generator to write state and
124 debugging information to STDOUT as it runs.
125 manifest - The "manifest" option, if provided, will cause a manifest
127 file to be created and written to disk. The manifest file contains a
128 list of all the test files generated, but listed in the prefered order
129 they should be processed to best satisfy the class-level dependency of
130 the tests.
131 check_count - The "check_count" value controls how strictly the test
133 script will watch the number of tests that have been executed.
134 When set to false, the script does no count checking other than the
136 standard total count for scripts (where all section counts are known)
137 When set to 1 (the default), "Test::Inline" does smart count checking,
139 doing section-by-section checking for known-count sections only when
140 the total for the entire script is not known.
141 When set to 2 or higher, "Test::Inline" does full count checking, doing
143 section-by-section checking for every section with a known number of
144 tests.
145 file_content - The "file_content" option should be provided as a CODE
147 reference, which will be passed as arguments the "Test::Inline" object,
148 and a single Test::Inline::Script object, and should return a string
149 containing the contents of the resulting test file. This will be
150 written to the "OutputHandler".
151 output - The "output" option provides the location of the directory
153 where the tests will be written to. It should both already exist, and
154 be writable. If using a custom "OutputHandler", the value of "output"
155 should refer to the location within the OutputHandler that the files
156 will be written to.
157 readonly - The "readonly" option, if provided, indicates that any
159 generated test files should be created (or set when updated) with read-
160 only permissions, to prevent accidentally adding to or editing the test
161 scripts directly (instead of via the classes).
162 This option is currently disabled by default, by may be enabled by
164 default in a future release, so if you do NOT want your tests being
165 created as read-only, you should explicitly set this option to false.
166 InputHandler - The "InputHandler" option, if provided, supplies an
168 alternative "FileHandler" from which source modules are retrieved.
169 OuputHandler - The "OutputHandler" option, if provided, supplies an
171 alternative "FileHandler" to which the resulting test scripts are
172 written.
173 Returns a new "Test::Inline" object on success.
175 Returns "undef" if there is a problem with one of the options.
177 exception
179 The "exception" method returns a flag which indicates whether error
180 will be returned via exceptions.
181 InputHandler
183 The "InputHandler" method returns the file handler object that will be
184 used to find and load the source code.
185 ExtractHandler
187 The "ExtractHandler" accessor returns the object that will be used to
188 extract the test sections from the source code.
189 ContentHandler
191 The "ContentHandler" accessor return the script content generation
192 handler.
193 OutputHandler
195 The "OutputHandler" accessor returns the file handler object that the
196 generated test scripts will be written to.
197 add $file, $directory, \$source, $Handle
199 The "add" method is a parameter-sensitive method for adding something
200 to the build schedule.
201 It takes as argument a file path, a directory path, a reference to a
203 SCALAR containing perl code, or an IO::Handle (or subclass) object. It
204 will retrieve code from the parameter as appropriate, parse it, and
205 create zero or more Test::Inline::Script objects representing the test
206 scripts that will be generated for that source code.
207 Returns the number of test scripts added, which could be zero, or
209 "undef" on error.
210 add_class
212 $Tests->add_class( 'Foo::Bar' );
213 $Tests->add_class( 'Foo::Bar', recursive => 1 );
214 The "add_class" method adds a class to the list of those to have their
216 tests generated. Optionally, the "recursive" option can be provided to
217 add not just the class you provide, but all classes below it as well.
218 Returns the number of classes found with inline tests, and added,
220 including 0 if no classes with tests are found. Returns "undef" if an
221 error occurs while adding the class or it's children.
222 add_all
224 The "add_all" method will search the "InputHandler" for all *.pm files,
225 and add them to the generation set.
226 Returns the total number of test scripts added, which may be zero, or
228 "undef" on error.
229 classes
231 The "classes" method returns a list of the names of all the classes
232 that have been added to the "Test::Inline" object, or the null list
233 "()" if nothing has been added.
234 class
236 For a given class name, fetches the Test::Inline::Script object for
237 that class, if it has been added to the "Test::Inline" object. Returns
238 "undef" if the class has not been added to the "Test::Inline" object.
239 filenames
241 For all of the classes added, the "filenames" method generates a map of
242 the filenames that the test files for the various classes should be
243 written to.
244 Returns a reference to a hash with the classes as keys, and filenames
246 as values.
247 Returns 0 if there are no files to write.
249 Returns "undef" on error.
251 schedule
253 While the "filenames" method generates a map of the files for the
254 various classes, the "schedule" returns the list of file names in the
255 order in which they should actually be executed.
256 Returns a reference to an array containing the file names as strings.
258 Returns 0 if there are no files to write.
260 Returns "undef" on error.
262 manifest
264 The "manifest" generates the contents of the manifest file, if it is
265 both wanted and needed.
266 Returns the contents of the manifest file as a normal string, false if
268 it is either not wanted or needed, or "undef" on error.
269 save
271 $Tests->save;
272 The "save" method generates the test files for all classes, and saves
274 them to the "output" directory.
275 Returns the number of test files generated. Returns "undef" on error.
277
279 The "Extended =begin" syntax used for non-trivial sections is not
280 formalised as part of the POD spec yet, although it is on the track to
281 being included.
282 While simple '=begin testing' sections are fine and will pass POD
284 testing, extended begin sections may cause POD errors.
285
287 - Add support for "example" sections
288 - Add support for "=for" sections
290
292 Bugs should always be submitted via the CPAN bug tracker
293 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>
295 Professional support, assistance, or customisations for large scale
297 uses of "Test::Inline" are available from <http://phase-n.com/>.
298 For other issues, contact the maintainer.
300
302 Adam Kennedy <adamk@cpan.org>
303
305 Thank you to Phase N (<http://phase-n.com/>) for permitting the open
306 sourcing and release of this distribution.
307
309 Copyright 2004 - 2013 Adam Kennedy.
310 This program is free software; you can redistribute it and/or modify it
312 under the same terms as Perl itself.
313 The full text of the license can be found in the LICENSE file included
315 with this module.
316perl v5.30.0 2019-07-26 Test::Inline(3)