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 version 2.214
11
13 Embedding tests allows tests to be placed near the code being tested.
14 This is a nice supplement to the traditional .t files.
16 How does it work?
18 "Test::Inline" lets you write small fragments of general or function-
19 specific testing code, and insert it anywhere you want in your modules,
20 inside a specific tagged POD segment, like the following.
21 =begin testing
23 # This code assumes we have a cpuinfo file
25 ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
26 =end testing
28 =begin testing label
30 # Test generation of the <label> HTML tag
32 is( My::HTML->label('foo'), '<label>foo</label>', '->label(simple) works' );
33 is( My::HTML->label('bar', 'foo'), '<label for="bar">foo</label>', '->label(for) works' );
34 =end testing
36 You can add as many, or as few, of these chunks of tests as you wish.
38 The key condition when writing them is that they should be logically
39 independant of each other. Each chunk of testing code should not die or
40 crash if it is run before or after another chunk.
41 Using inline2test or another test compiler, you can then transform
43 these chunks in a test script, or an entire tree of modules into a
44 complete set of standard Test::More-based test scripts.
45 These test scripts can then be executed as normal.
47 What is Test::Inline good for?
49 "Test::Inline" is incredibly useful for doing ad-hoc unit testing.
50 In any large groups of modules, you can add testing code here, there
52 and everywhere, anywhere you want. The next time the test compiler is
53 run, a new test script will just appear.
54 This also makes it great for testing assumptions you normally wouldn't
56 bother to write run-time code to test. It ensures that your assumptions
57 about the way Perl does some operation, or about the state of the host,
58 are confirmed at install-time.
59 If your assumption is ever wrong, it gets picked up at install-time and
61 based on the test failures, you can correct your assumption.
62 It's also extremely useful for systematically testing self-contained
64 code.
65 That is, any code which can be independantly tested without the need
67 for external systems such as databases, and that has no side-effects on
68 external systems.
69 All of this code, written by multiple people, can then have one single
71 set of test files generated. You can check all the bits and pieces of a
72 large API, or anything you like, in fine detail.
73 Test::Inline also introduces the concept of unit-tested documentation.
75 Not only can your code be tested, but if you have a FAQ or some other
77 pure documentation module, you can validate that the documentation is
78 correct for the version of the module installed.
79 If the module ever changes to break the documentation, you can catch it
81 and correct the documentation.
82 What is Test::Inline bad for?
84 "Test::Inline" is not a complete testing solution, and there are
85 several 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
96 start with a number (for ordering purposes), the first step is to
97 create your normal test scripts using file names in the CPAN style of
98 01_compile.t, 02_main.t, 03_foobar.t, and so on.
99 You can then add your testing fragments wherever you like throughout
101 your code, and use the inline2test script to generate the test scripts
102 for the inline tests. By default the test scripts will be named after
103 the packages/classes that the test fragments are found in.
104 Tests for Class::Name will end up in the file "class_name.t".
106 These test files sit quite happily alongside your number test scripts.
108 When you run the test suite as you normally would, the inline scripts
110 will be run after the numbered tests.
111
113 new
114 my $Tests = Test::Inline->new(
115 verbose => 1,
116 readonly => 1,
117 output => 'auto',
118 manifest => 'auto/manifest',
119 );
120 The "new" constructor creates a new test generation framework. Once the
122 constructor has been used to create the generator, the "add_class"
123 method can be used to specify classes, or class heirachies, to generate
124 tests for.
125 verbose - The "verbose" option causes the generator to write state and
127 debugging information to STDOUT as it runs.
128 manifest - The "manifest" option, if provided, will cause a manifest
130 file to be created and written to disk. The manifest file contains a
131 list of all the test files generated, but listed in the prefered order
132 they should be processed to best satisfy the class-level dependency of
133 the tests.
134 check_count - The "check_count" value controls how strictly the test
136 script will watch the number of tests that have been executed.
137 When set to false, the script does no count checking other than the
139 standard total count for scripts (where all section counts are known)
140 When set to 1 (the default), "Test::Inline" does smart count checking,
142 doing section-by-section checking for known-count sections only when
143 the total for the entire script is not known.
144 When set to 2 or higher, "Test::Inline" does full count checking, doing
146 section-by-section checking for every section with a known number of
147 tests.
148 file_content - The "file_content" option should be provided as a CODE
150 reference, which will be passed as arguments the "Test::Inline" object,
151 and a single Test::Inline::Script object, and should return a string
152 containing the contents of the resulting test file. This will be
153 written to the "OutputHandler".
154 output - The "output" option provides the location of the directory
156 where the tests will be written to. It should both already exist, and
157 be writable. If using a custom "OutputHandler", the value of "output"
158 should refer to the location within the OutputHandler that the files
159 will be written to.
160 readonly - The "readonly" option, if provided, indicates that any
162 generated test files should be created (or set when updated) with read-
163 only permissions, to prevent accidentally adding to or editing the test
164 scripts directly (instead of via the classes).
165 This option is currently disabled by default, by may be enabled by
167 default in a future release, so if you do NOT want your tests being
168 created as read-only, you should explicitly set this option to false.
169 InputHandler - The "InputHandler" option, if provided, supplies an
171 alternative "FileHandler" from which source modules are retrieved.
172 OuputHandler - The "OutputHandler" option, if provided, supplies an
174 alternative "FileHandler" to which the resulting test scripts are
175 written.
176 Returns a new "Test::Inline" object on success.
178 Returns "undef" if there is a problem with one of the options.
180 exception
182 The "exception" method returns a flag which indicates whether error
183 will be returned via exceptions.
184 InputHandler
186 The "InputHandler" method returns the file handler object that will be
187 used to find and load the source code.
188 ExtractHandler
190 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
195 handler.
196 OutputHandler
198 The "OutputHandler" accessor returns the file handler object that the
199 generated test scripts will be written to.
200 add $file, $directory, \$source, $Handle
202 The "add" method is a parameter-sensitive method for adding something
203 to the build schedule.
204 It takes as argument a file path, a directory path, a reference to a
206 SCALAR containing perl code, or an IO::Handle (or subclass) object. It
207 will retrieve code from the parameter as appropriate, parse it, and
208 create zero or more Test::Inline::Script objects representing the test
209 scripts that will be generated for that source code.
210 Returns the number of test scripts added, which could be zero, or
212 "undef" on error.
213 add_class
215 $Tests->add_class( 'Foo::Bar' );
216 $Tests->add_class( 'Foo::Bar', recursive => 1 );
217 The "add_class" method adds a class to the list of those to have their
219 tests generated. Optionally, the "recursive" option can be provided to
220 add not just the class you provide, but all classes below it as well.
221 Returns the number of classes found with inline tests, and added,
223 including 0 if no classes with tests are found. Returns "undef" if an
224 error occurs while adding the class or it's children.
225 add_all
227 The "add_all" method will search the "InputHandler" for all *.pm files,
228 and add them to the generation set.
229 Returns the total number of test scripts added, which may be zero, or
231 "undef" on error.
232 classes
234 The "classes" method returns a list of the names of all the classes
235 that have been added to the "Test::Inline" object, or the null list
236 "()" if nothing has been added.
237 class
239 For a given class name, fetches the Test::Inline::Script object for
240 that class, if it has been added to the "Test::Inline" object. Returns
241 "undef" if the class has not been added to the "Test::Inline" object.
242 filenames
244 For all of the classes added, the "filenames" method generates a map of
245 the filenames that the test files for the various classes should be
246 written to.
247 Returns a reference to a hash with the classes as keys, and filenames
249 as values.
250 Returns 0 if there are no files to write.
252 Returns "undef" on error.
254 schedule
256 While the "filenames" method generates a map of the files for the
257 various classes, the "schedule" returns the list of file names in the
258 order in which they should actually be executed.
259 Returns a reference to an array containing the file names as strings.
261 Returns 0 if there are no files to write.
263 Returns "undef" on error.
265 manifest
267 The "manifest" generates the contents of the manifest file, if it is
268 both wanted and needed.
269 Returns the contents of the manifest file as a normal string, false if
271 it is either not wanted or needed, or "undef" on error.
272 save
274 $Tests->save;
275 The "save" method generates the test files for all classes, and saves
277 them to the "output" directory.
278 Returns the number of test files generated. Returns "undef" on error.
280
282 - Add support for "example" sections
283 - Add support for "=for" sections
285
287 Thank you to Phase N (<http://phase-n.com/>) for permitting the open
288 sourcing and release of this distribution.
289
291 The "Extended =begin" syntax used for non-trivial sections is not
292 formalised as part of the POD spec yet, although it is on the track to
293 being included.
294 While simple '=begin testing' sections are fine and will pass POD
296 testing, extended begin sections may cause POD errors.
297 Bugs may be submitted through the RT bug tracker
299 <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-Inline> (or
300 bug-Test-Inline@rt.cpan.org <mailto:bug-Test-Inline@rt.cpan.org>).
301
303 Adam Kennedy <adamk@cpan.org>
304
306 • Adam Kennedy <adam@ali.as>
307 • Karen Etheridge <ether@cpan.org>
309 • Ricardo Signes <rjbs@cpan.org>
311
313 This software is copyright (c) 2003 by Adam Kennedy.
314 This is free software; you can redistribute it and/or modify it under
316 the same terms as the Perl 5 programming language system itself.
317perl v5.34.0 2021-07-23 Test::Inline(3)