1Test::Inline(3)       User Contributed Perl Documentation      Test::Inline(3)
2
3
4

NAME

6       Test::Inline - Embed your tests in your code, next to what is being
7       tested
8

DESCRIPTION

10       Embedding tests allows tests to be placed near the code being tested.
11
12       This is a nice supplement to the traditional .t files.
13
14   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
19         =begin testing
20
21         # This code assumes we have a cpuinfo file
22         ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
23
24         =end testing
25
26         =begin testing label
27
28         # 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
32         =end testing
33
34       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
39       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
43       These test scripts can then be executed as normal.
44
45   What is Test::Inline good for?
46       "Test::Inline" is incredibly useful for doing ad-hoc unit testing.
47
48       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
52       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
57       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
60       It's also extremely useful for systematically testing self-contained
61       code.
62
63       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
67       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
71       Test::Inline also introduces the concept of unit-tested documentation.
72
73       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
77       If the module ever changes to break the documentation, you can catch it
78       and correct the documentation.
79
80   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
84       ·   Static testing across the entire codebase
85
86       ·   Functional testing
87
88       ·   Tests with side-effects such as those that might change a testing
89           database
90
91   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
97       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
102       Tests for Class::Name will end up in the file "class_name.t".
103
104       These test files sit quite happily alongside your number test scripts.
105
106       When you run the test suite as you normally would, the inline scripts
107       will be run after the numbered tests.
108

METHODS

110   new
111         my $Tests = Test::Inline->new(
112             verbose  => 1,
113             readonly => 1,
114             output   => 'auto',
115             manifest => 'auto/manifest',
116         );
117
118       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
123       verbose - The "verbose" option causes the generator to write state and
124       debugging information to STDOUT as it runs.
125
126       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
132       check_count - The "check_count" value controls how strictly the test
133       script will watch the number of tests that have been executed.
134
135       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
138       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
142       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
146       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
152       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
158       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
163       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
167       InputHandler - The "InputHandler" option, if provided, supplies an
168       alternative "FileHandler" from which source modules are retrieved.
169
170       OuputHandler - The "OutputHandler" option, if provided, supplies an
171       alternative "FileHandler" to which the resulting test scripts are
172       written.
173
174       Returns a new "Test::Inline" object on success.
175
176       Returns "undef" if there is a problem with one of the options.
177
178   exception
179       The "exception" method returns a flag which indicates whether error
180       will be returned via exceptions.
181
182   InputHandler
183       The "InputHandler" method returns the file handler object that will be
184       used to find and load the source code.
185
186   ExtractHandler
187       The "ExtractHandler" accessor returns the object that will be used to
188       extract the test sections from the source code.
189
190   ContentHandler
191       The "ContentHandler" accessor return the script content generation
192       handler.
193
194   OutputHandler
195       The "OutputHandler" accessor returns the file handler object that the
196       generated test scripts will be written to.
197
198   add $file, $directory, \$source, $Handle
199       The "add" method is a parameter-sensitive method for adding something
200       to the build schedule.
201
202       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
208       Returns the number of test scripts added, which could be zero, or
209       "undef" on error.
210
211   add_class
212         $Tests->add_class( 'Foo::Bar' );
213         $Tests->add_class( 'Foo::Bar', recursive => 1 );
214
215       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
219       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
223   add_all
224       The "add_all" method will search the "InputHandler" for all *.pm files,
225       and add them to the generation set.
226
227       Returns the total number of test scripts added, which may be zero, or
228       "undef" on error.
229
230   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
235   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
240   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
245       Returns a reference to a hash with the classes as keys, and filenames
246       as values.
247
248       Returns 0 if there are no files to write.
249
250       Returns "undef" on  error.
251
252   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
257       Returns a reference to an array containing the file names as strings.
258
259       Returns 0 if there are no files to write.
260
261       Returns "undef" on error.
262
263   manifest
264       The "manifest" generates the contents of the manifest file, if it is
265       both wanted and needed.
266
267       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
270   save
271         $Tests->save;
272
273       The "save" method generates the test files for all classes, and saves
274       them to the "output" directory.
275
276       Returns the number of test files generated. Returns "undef" on error.
277

BUGS

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
283       While simple '=begin testing' sections are fine and will pass POD
284       testing, extended begin sections may cause POD errors.
285

TO DO

287       - Add support for "example" sections
288
289       - Add support for "=for" sections
290

SUPPORT

292       Bugs should always be submitted via the CPAN bug tracker
293
294       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-Inline>
295
296       Professional support, assistance, or customisations for large scale
297       uses of "Test::Inline" are available from <http://phase-n.com/>.
298
299       For other issues, contact the maintainer.
300

AUTHOR

302       Adam Kennedy <adamk@cpan.org>
303

ACKNOWLEDGEMENTS

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
311       This program is free software; you can redistribute it and/or modify it
312       under the same terms as Perl itself.
313
314       The full text of the license can be found in the LICENSE file included
315       with this module.
316
317
318
319perl v5.32.0                      2020-07-28                   Test::Inline(3)
Impressum