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

VERSION

10       version 2.214
11

DESCRIPTION

13       Embedding tests allows tests to be placed near the code being tested.
14
15       This is a nice supplement to the traditional .t files.
16
17   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
22         =begin testing
23
24         # This code assumes we have a cpuinfo file
25         ok( -f /proc/cpuinfo, 'Host has a standard /proc/cpuinfo file' );
26
27         =end testing
28
29         =begin testing label
30
31         # 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
35         =end testing
36
37       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
42       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
46       These test scripts can then be executed as normal.
47
48   What is Test::Inline good for?
49       "Test::Inline" is incredibly useful for doing ad-hoc unit testing.
50
51       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
55       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
60       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
63       It's also extremely useful for systematically testing self-contained
64       code.
65
66       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
70       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
74       Test::Inline also introduces the concept of unit-tested documentation.
75
76       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
80       If the module ever changes to break the documentation, you can catch it
81       and correct the documentation.
82
83   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
87       •   Static testing across the entire codebase
88
89       •   Functional testing
90
91       •   Tests with side-effects such as those that might change a testing
92           database
93
94   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
100       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
105       Tests for Class::Name will end up in the file "class_name.t".
106
107       These test files sit quite happily alongside your number test scripts.
108
109       When you run the test suite as you normally would, the inline scripts
110       will be run after the numbered tests.
111

METHODS

113   new
114         my $Tests = Test::Inline->new(
115             verbose  => 1,
116             readonly => 1,
117             output   => 'auto',
118             manifest => 'auto/manifest',
119         );
120
121       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
126       verbose - The "verbose" option causes the generator to write state and
127       debugging information to STDOUT as it runs.
128
129       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
135       check_count - The "check_count" value controls how strictly the test
136       script will watch the number of tests that have been executed.
137
138       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
141       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
145       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
149       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
155       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
161       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
166       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
170       InputHandler - The "InputHandler" option, if provided, supplies an
171       alternative "FileHandler" from which source modules are retrieved.
172
173       OuputHandler - The "OutputHandler" option, if provided, supplies an
174       alternative "FileHandler" to which the resulting test scripts are
175       written.
176
177       Returns a new "Test::Inline" object on success.
178
179       Returns "undef" if there is a problem with one of the options.
180
181   exception
182       The "exception" method returns a flag which indicates whether error
183       will be returned via exceptions.
184
185   InputHandler
186       The "InputHandler" method returns the file handler object that will be
187       used to find and load the source code.
188
189   ExtractHandler
190       The "ExtractHandler" accessor returns the object that will be used to
191       extract the test sections from the source code.
192
193   ContentHandler
194       The "ContentHandler" accessor return the script content generation
195       handler.
196
197   OutputHandler
198       The "OutputHandler" accessor returns the file handler object that the
199       generated test scripts will be written to.
200
201   add $file, $directory, \$source, $Handle
202       The "add" method is a parameter-sensitive method for adding something
203       to the build schedule.
204
205       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
211       Returns the number of test scripts added, which could be zero, or
212       "undef" on error.
213
214   add_class
215         $Tests->add_class( 'Foo::Bar' );
216         $Tests->add_class( 'Foo::Bar', recursive => 1 );
217
218       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
222       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
226   add_all
227       The "add_all" method will search the "InputHandler" for all *.pm files,
228       and add them to the generation set.
229
230       Returns the total number of test scripts added, which may be zero, or
231       "undef" on error.
232
233   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
238   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
243   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
248       Returns a reference to a hash with the classes as keys, and filenames
249       as values.
250
251       Returns 0 if there are no files to write.
252
253       Returns "undef" on  error.
254
255   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
260       Returns a reference to an array containing the file names as strings.
261
262       Returns 0 if there are no files to write.
263
264       Returns "undef" on error.
265
266   manifest
267       The "manifest" generates the contents of the manifest file, if it is
268       both wanted and needed.
269
270       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
273   save
274         $Tests->save;
275
276       The "save" method generates the test files for all classes, and saves
277       them to the "output" directory.
278
279       Returns the number of test files generated. Returns "undef" on error.
280

TO DO

282       - Add support for "example" sections
283
284       - Add support for "=for" sections
285

ACKNOWLEDGEMENTS

287       Thank you to Phase N (<http://phase-n.com/>) for permitting the open
288       sourcing and release of this distribution.
289

BUGS

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
295       While simple '=begin testing' sections are fine and will pass POD
296       testing, extended begin sections may cause POD errors.
297
298       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

AUTHOR

303       Adam Kennedy <adamk@cpan.org>
304

CONTRIBUTORS

306       •   Adam Kennedy <adam@ali.as>
307
308       •   Karen Etheridge <ether@cpan.org>
309
310       •   Ricardo Signes <rjbs@cpan.org>
311
313       This software is copyright (c) 2003 by Adam Kennedy.
314
315       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.
317
318
319
320perl v5.38.0                      2023-07-21                   Test::Inline(3)
Impressum