Test::Compile(3pm)

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

NAME

6       Test::Compile - Check whether Perl files compile correctly.
7

SYNOPSIS

9           # The OO way (recommended)
10           use Test::Compile;
11           my $test = Test::Compile->new();
12           $test->all_files_ok();
13           $test->done_testing();
14
15           # The procedural way (deprecated)
16           use Test::Compile;
17           all_pm_files_ok();
18

DESCRIPTION

20       "Test::Compile" lets you check the whether your perl modules and
21       scripts compile properly, and report its results in standard
22       "Test::Simple" fashion.
23
24       The basic usage - as shown above, will locate your perl files and test
25       that they all compile.
26
27       Module authors can (and probably should) include the following in a
28       t/00-compile.t file and have "Test::Compile" automatically find and
29       check all Perl files in a module distribution:
30
31           #!perl
32           use strict;
33           use warnings;
34           use Test::Compile;
35           my $test = Test::Compile->new();
36           $test->all_files_ok();
37           $test->done_testing();
38

METHODS

40       "new()"
41           A basic constructor, nothing special except that it returns a
42           Test::Compile::Internal object.
43
44       "all_files_ok(@dirs)"
45           Checks all the perl files it can find for compilation errors.
46
47           If @dirs is defined then it is taken as an array of directories to
48           be searched for perl files, otherwise it searches some default
49           locations - see "all_pm_files()" and "all_pl_files()".
50
51       "all_pm_files(@dirs)"
52           Returns a list of all the perl module files - that is any files
53           ending in .pm in @dirs and in directories below. If @dirs is
54           undefined, it searches blib if blib exists, or else lib.
55
56           Skips any files in "CVS" or ".svn" directories.
57
58           The order of the files returned is machine-dependent. If you want
59           them sorted, you'll have to sort them yourself.
60
61       "all_pl_files(@dirs)"
62           Returns a list of all the perl script files - that is, any files in
63           @dirs that either have a .pl extension, or have no extension and
64           have a perl shebang line.
65
66           If @dirs is undefined, it searches script if script exists, or else
67           bin if bin exists.
68
69           Skips any files in "CVS" or ".svn" directories.
70
71           The order of the files returned is machine-dependent. If you want
72           them sorted, you'll have to sort them yourself.
73
74       "pl_file_compiles($file)"
75           Returns true if $file compiles as a perl script.
76
77       "pm_file_compiles($file)"
78           Returns true if $file compiles as a perl module.
79
80       "verbose($verbose)"
81           An accessor to get/set the verbose flag.  If "verbose" is set, you
82           can get some extra diagnostics when compilation fails.
83
84           Verbose is set on by default.
85
86   Test Methods
87       "Test::Compile::Internal" encapsulates a "Test::Builder" object, and
88       provides access to some of its methods.
89
90       "done_testing()"
91           Declares that you are done testing, no more tests will be run after
92           this point.
93
94       "ok($test, $name)"
95           Your basic test. Pass if $test is true, fail if $test is false.
96           Just like "Test::Simple"'s "ok()".
97
98       "plan($count)"
99           Defines how many tests you plan to run.
100
101       "exported_to($caller)"
102           Tells "Test::Builder" what package you exported your functions to.
103           I am not sure why you would want to do that, or whether it would do
104           you any good.
105
106       "diag(@msgs)"
107           Prints out the given @msgs. Like print, arguments are simply
108           appended together.
109
110           Output will be indented and marked with a # so as not to interfere
111           with test output. A newline will be put on the end if there isn't
112           one already.
113
114           We encourage using this rather than calling print directly.
115
116       "skip($reason)"
117           Skips the current test, reporting the $reason.
118
119       "skip_all($reason)"
120           Skips all the tests, using the given $reason. Exits immediately
121           with 0.
122

FUNCTIONS

124       The use of the following functions is deprecated and strongly
125       discouraged.
126
127       They are automatically exported to your namespace,  which is no longer
128       considered best practise.  At some stage in the future, this will stop
129       and you'll have to import them explicitly.
130
131       Even then, you really should use the object oriented methods as they
132       provide a more consistent interface.
133
134       "all_pm_files_ok(@files)"
135           Checks all the perl module files it can find for compilation
136           errors.
137
138           It uses "all_pm_files(@files)" to find the perl module files.
139
140           It also calls the "plan()" function for you (one test for each
141           module), so you can't have already called "plan". Unfortunately,
142           this also means you can't use this function with
143           "all_pl_files_ok()".  If this is a problem you should really be
144           using the object oriented interface.
145
146           Returns true if all Perl module files are ok, or false if any fail.
147
148           Module authors can include the following in a t/00_compile.t file
149           and have "Test::Compile" automatically find and check all Perl
150           module files in a module distribution:
151
152               #!perl -w
153               use strict;
154               use warnings;
155               use Test::More;
156               eval "use Test::Compile";
157               Test::More->builder->BAIL_OUT(
158                   "Test::Compile required for testing compilation") if $@;
159               all_pm_files_ok();
160
161       "all_pl_files_ok(@files)"
162           Checks all the perl script files it can find for compilation
163           errors.
164
165           It uses "all_pl_files(@files)" to find the perl script files.
166
167           It also calls the "plan()" function for you (one test for each
168           script), so you can't have already called "plan". Unfortunately,
169           this also means you can't use this function with
170           "all_pm_files_ok()".  If this is a problem you should really be
171           using the object oriented interface.
172
173           Returns true if all Perl script files are ok, or false if any fail.
174
175           Module authors can include the following in a
176           t/00_compile_scripts.t file and have "Test::Compile" automatically
177           find and check all Perl script files in a module distribution:
178
179               #!perl -w
180               use strict;
181               use warnings;
182               use Test::More;
183               eval "use Test::Compile";
184               plan skip_all => "Test::Compile required for testing compilation"
185                 if $@;
186               all_pl_files_ok();
187
188       "pm_file_ok($filename, $testname)"
189           "pm_file_ok()" will okay the test if $filename compiles as a perl
190           module.
191
192           The optional second argument $testname is the name of the test. If
193           it is omitted, "pm_file_ok()" chooses a default test name "Compile
194           test for $filename".
195
196       "pl_file_ok($filename, $testname)"
197           "pl_file_ok()" will okay the test if $filename compiles as a perl
198           script. You need to give the path to the script relative to this
199           distribution's base directory. So if you put your scripts in a
200           'top-level' directory called script the argument would be
201           "script/filename".
202
203           The optional second argument $testname is the name of the test. If
204           it is omitted, "pl_file_ok()" chooses a default test name "Compile
205           test for $filename".
206
207       "all_pm_files(@dirs)"
208           Returns a list of all the perl module files - that is, files ending
209           in .pm - in @dirs and in directories below. If no directories are
210           passed, it defaults to blib if blib exists, or else lib if not.
211           Skips any files in "CVS" or ".svn" directories.
212
213           The order of the files returned is machine-dependent. If you want
214           them sorted, you'll have to sort them yourself.
215
216       "all_pl_files(@dirs)"
217           Returns a list of all the perl script files - that is, any files in
218           @dirs that either have a .pl extension, or have no extension and
219           have a perl shebang line.
220
221           If @dirs is undefined, it searches script if script exists, or else
222           bin if bin exists.
223
224           Skips any files in "CVS" or ".svn" directories.
225
226           The order of the files returned is machine-dependent. If you want
227           them sorted, you'll have to sort them yourself.
228

AUTHORS

230       Sagar R. Shah "<srshah@cpan.org>", Marcel Grünauer,
231       "<marcel@cpan.org>", Evan Giles, "<egiles@cpan.org>"
232

COPYRIGHT AND LICENSE

234       Copyright 2007-2015 by the authors.
235
236       This library is free software; you can redistribute it and/or modify it
237       under the same terms as Perl itself.
238