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-
17 specific testing code, and insert it anywhere you want in your modules,
18 inside a specific tagged POD segment, like the following.
19 =begin testing
21 # This code assumes we have a cpuinfo file
23 ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
24 =end testing
26 =begin testing label
28 # Test generation of the <label> HTML tag
30 is( My::HTML->label('foo'), '<label>foo</label>', '->label(simple) works' );
31 is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works' );
32 =end testing
34 You can add as many, or as few, of these chunks of tests as you wish.
36 The key condition when writing them is that they should be logically
37 independant of each other. Each chunk of testing code should not die or
38 crash if it is run before or after another chunk.
39 Using inline2test or another test compiler, you can then transform
41 these chunks in a test script, or an entire tree of modules into a com‐
42 plete set of standard Test::More-based test scripts.
43 These test scripts can then be executed as normal.
45 What is Test::Inline good for?
47 "Test::Inline" is incredibly useful for doing ad-hoc unit testing.
49 In any large groups of modules, you can add testing code here, there
51 and everywhere, anywhere you want. The next time the test compiler is
52 run, a new test script will just appear.
53 This also makes it great for testing assumptions you normally wouldn't
55 bother to write run-time code to test. It ensures that your assumptions
56 about the way Perl does some operation, or about the state of the host,
57 are confirmed at install-time.
58 If your assumption is ever wrong, it gets picked up at install-time and
60 based on the test failures, you can correct your assumption.
61 It's also extremely useful for systematically testing self-contained
63 code.
64 That is, any code which can be independantly tested without the need
66 for external systems such as databases, and that has no side-effects on
67 external systems.
68 All of this code, written by multiple people, can then have one single
70 set of test files generated. You can check all the bits and pieces of a
71 large API, or anything you like, in fine detail.
72 Test::Inline also introduces the concept of unit-tested documentation.
74 Not only can your code be tested, but if you have a FAQ or some other
76 pure documentation module, you can validate that the documentation is
77 correct for the version of the module installed.
78 If the module ever changes to break the documentation, you can catch it
80 and correct the documentation.
81 What is Test::Inline bad for?
83 "Test::Inline" is not a complete testing solution, and there are sev‐
85 eral types of testing you probably DON'T want to use it for.
86 · Static testing across the entire codebase
88 · Functional testing
90 · Tests with side-effects such as those that might change a testing
92 database
93 Getting Started
95 Because Test::Inline creates test scripts with file names that don't
97 start with a number (for ordering purposes), the first step is to cre‐
98 ate your normal test scripts using file names in the CPAN style of
99 01_compile.t, 02_main.t, 03_foobar.t, and so on.
100 You can then add your testing fragments wherever you like throughout
102 your code, and use the inline2test script to generate the test scripts
103 for the inline tests. By default the test scripts will be named after
104 the packages/classes that the test fragments are found in.
105 Tests for Class::Name will end up in the file "class_name.t".
107 These test files sit quite happily alongside your number test scripts.
109 When you run the test suite as you normally would, the inline scripts
111 will be run after the numbered tests.
112
114 new
115 my $Tests = Test::Inline->new(
117 verbose => 1,
118 readonly => 1,
119 output => 'auto',
120 manifest => 'auto/manifest',
121 );
122 The "new" constructor creates a new test generation framework. Once the
124 constructor has been used to create the generator, the "add_class"
125 method can be used to specify classes, or class heirachies, to generate
126 tests for.
127 verbose - The "verbose" option causes the generator to write state and
129 debugging information to STDOUT as it runs.
130 manifest - The "manifest" option, if provided, will cause a manifest
132 file to be created and written to disk. The manifest file contains a
133 list of all the test files generated, but listed in the prefered order
134 they should be processed to best satisfy the class-level dependency of
135 the tests.
136 check_count - The "check_count" value controls how strictly the test
138 script will watch the number of tests that have been executed.
139 When set to false, the script does no count checking other than the
141 standard total count for scripts (where all section counts are known)
142 When set to 1 (the default), "Test::Inline" does smart count checking,
144 doing section-by-section checking for known-count sections only when
145 the total for the entire script is not known.
146 When set to 2 or higher, "Test::Inline" does full count checking, doing
148 section-by-section checking for every section with a known number of
149 tests.
150 file_content - The "file_content" option should be provided as a CODE
152 reference, which will be passed as arguments the "Test::Inline" object,
153 and a single Test::Inline::Script object, and should return a string
154 containing the contents of the resulting test file. This will be writ‐
155 ten to the "OutputHandler".
156 output - The "output" option provides the location of the directory
158 where the tests will be written to. It should both already exist, and
159 be writable. If using a custom "OutputHandler", the value of "output"
160 should refer to the location within the OutputHandler that the files
161 will be written to.
162 readonly - The "readonly" option, if provided, indicates that any gen‐
164 erated test files should be created (or set when updated) with read-
165 only permissions, to prevent accidentally adding to or editing the test
166 scripts directly (instead of via the classes).
167 This option is currently disabled by default, by may be enabled by
169 default in a future release, so if you do NOT want your tests being
170 created as read-only, you should explicitly set this option to false.
171 InputHandler - The "InputHandler" option, if provided, supplies an
173 alternative "FileHandler" from which source modules are retrieved.
174 OuputHandler - The "OutputHandler" option, if provided, supplies an
176 alternative "FileHandler" to which the resulting test scripts are writ‐
177 ten.
178 Returns a new "Test::Inline" object on success.
180 Returns "undef" if there is a problem with one of the options.
182 InputHandler
184 The "InputHandler" method returns the file handler object that will be
186 used to find and load the source code.
187 ExtractHandler
189 The "ExtractHandler" accessor returns the object that will be used to
191 extract the test sections from the source code.
192 ContentHandler
194 The "ContentHandler" accessor return the script content generation han‐
196 dler.
197 OutputHandler
199 The "OutputHandler" accessor returns the file handler object that the
201 generated test scripts will be written to.
202 add $file, $directory, \$source, $Handle
204 The "add" method is a parameter-sensitive method for adding something
206 to the build schedule.
207 It takes as argument a file path, a directory path, a reference to a
209 SCALAR containing perl code, or an IO::Handle (or subclass) object. It
210 will retrieve code from the parameter as appropriate, parse it, and
211 create zero or more Test::Inline::Script objects representing the test
212 scripts that will be generated for that source code.
213 Returns the number of test scripts added, which could be zero, or
215 "undef" on error.
216 add_class
218 $Tests->add_class( 'Foo::Bar' );
220 $Tests->add_class( 'Foo::Bar', recursive => 1 );
221 The "add_class" method adds a class to the list of those to have their
223 tests generated. Optionally, the "recursive" option can be provided to
224 add not just the class you provide, but all classes below it as well.
225 Returns the number of classes found with inline tests, and added,
227 including 0 if no classes with tests are found. Returns "undef" if an
228 error occurs while adding the class or it's children.
229 add_all
231 The "add_all" method will search the "InputHandler" for all *.pm files,
233 and add them to the generation set.
234 Returns the total number of test scripts added, which may be zero, or
236 "undef" on error.
237 classes
239 The "classes" method returns a list of the names of all the classes
241 that have been added to the "Test::Inline" object, or the null list
242 "()" if nothing has been added.
243 class
245 For a given class name, fetches the Test::Inline::Script object for
247 that class, if it has been added to the "Test::Inline" object. Returns
248 "undef" if the class has not been added to the "Test::Inline" object.
249 filenames
251 For all of the classes added, the "filenames" method generates a map of
253 the filenames that the test files for the various classes should be
254 written to.
255 Returns a reference to a hash with the classes as keys, and filenames
257 as values.
258 Returns 0 if there are no files to write.
260 Returns "undef" on error.
262 schedule
264 While the "filenames" method generates a map of the files for the vari‐
266 ous classes, the "schedule" returns the list of file names in the order
267 in which they should actually be executed.
268 Returns a reference to an array containing the file names as strings.
270 Returns 0 if there are no files to write.
272 Returns "undef" on error.
274 manifest
276 The "manifest" generates the contents of the manifest file, if it is
278 both wanted and needed.
279 Returns the contents of the manifest file as a normal string, false if
281 it is either not wanted or needed, or "undef" on error.
282 save
284 $Tests->save;
286 The "save" method generates the test files for all classes, and saves
288 them to the "output" directory.
289 Returns the number of test files generated. Returns "undef" on error.
291
293 The "Extended =begin" syntax used for non-trivial sections is not for‐
294 malised as part of the POD spec yet, although it is on the track to
295 being included.
296 While simple '=begin testing' sections are fine and will pass POD test‐
298 ing, extended begin sections may cause POD errors.
299
301 - Add support for "example" sections
302 - Add support for "=for" sections
304
306 Bugs should always be submitted via the CPAN bug tracker
307 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>
309 Professional support, assistance, or customisations for large scale
311 uses of "Test::Inline" are available from <http://phase-n.com/>.
312 For other issues, contact the maintainer.
314
316 Adam Kennedy <adamk@cpan.org>
317
319 Thank you to Phase N (<http://phase-n.com/>) for permitting the open
320 sourcing and release of this distribution.
321
323 Copyright 2004 - 2007 Adam Kennedy.
324 This program is free software; you can redistribute it and/or modify it
326 under the same terms as Perl itself.
327 The full text of the license can be found in the LICENSE file included
329 with this module.
330perl v5.8.8 2007-08-17 Test::Inline(3)