Test::Compile(3pm)

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

NAME

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

SYNOPSIS

9           #!perl -w
10           use strict;
11           use warnings;
12           use Test::Compile;
13           all_pm_files_ok();
14

DESCRIPTION

16       "Test::Compile" lets you check the validity of a Perl module file or
17       Perl script file, and report its results in standard "Test::Simple"
18       fashion.
19
20           BEGIN {
21               use Test::Compile tests => $num_tests;
22               pm_file_ok($file, "Valid Perl module file");
23           }
24
25       It's probably a good idea to run this in a BEGIN block. The examples
26       below omit it for clarity.
27
28       Module authors can include the following in a t/00_compile.t file and
29       have "Test::Compile" automatically find and check all Perl module files
30       in a module distribution:
31
32           use Test::More;
33           eval "use Test::Compile 0.09";
34           Test::More->builder->BAIL_OUT(
35               "Test::Compile 0.09 required for testing compilation") if $@;
36           all_pm_files_ok();
37
38       You can also specify a list of files to check, using the
39       "all_pm_files()" function supplied:
40
41           use strict;
42           use Test::More;
43           eval "use Test::Compile 0.09";
44           Test::More->builder->BAIL_OUT(
45               "Test::Compile 0.09 required for testing compilation") if $@;
46           my @pmdirs = qw(blib script);
47           all_pm_files_ok(all_pm_files(@pmdirs));
48
49       Or even (if you're running under Apache::Test):
50
51           use strict;
52           use Test::More;
53           eval "use Test::Compile 0.09";
54           Test::More->builder->BAIL_OUT(
55               "Test::Compile 0.09 required for testing compilation") if $@;
56
57           my @pmdirs = qw(blib script);
58           use File::Spec::Functions qw(catdir updir);
59           all_pm_files_ok(
60               all_pm_files(map { catdir updir, $_ } @pmdirs)
61           );
62
63       Why do the examples use "BAIL_OUT()" instead of "skip_all()"? Because
64       testing whether a module compiles is important. "skip_all()" is ok to
65       use with Test::Pod, because if the pod is malformed the program is
66       still going to run. But checking whether a module even compiles is
67       something else.  Test::Compile should be mandatory, not optional.
68

FUNCTIONS

70       "pm_file_ok(FILENAME[, TESTNAME ])"
71           "pm_file_ok()" will okay the test if the Perl module compiles
72           correctly.
73
74           When it fails, "pm_file_ok()" will show any compilation errors as
75           diagnostics.
76
77           The optional second argument "TESTNAME" is the name of the test. If
78           it is omitted, "pm_file_ok()" chooses a default test name "Compile
79           test for FILENAME".
80
81       "pl_file_ok(FILENAME[, TESTNAME ])"
82           "pl_file_ok()" will okay the test if the Perl script compiles
83           correctly. You need to give the path to the script relative to this
84           distribution's base directory. So if you put your scripts in a
85           'top-level' directory called script the argument would be
86           "script/filename".
87
88           When it fails, "pl_file_ok()" will show any compilation errors as
89           diagnostics.
90
91           The optional second argument "TESTNAME" is the name of the test. If
92           it is omitted, "pl_file_ok()" chooses a default test name "Compile
93           test for FILENAME".
94
95       "all_pm_files_ok([@files/@directories])"
96           Checks all the files in @files for compilation. It runs
97           all_pm_files() on each file/directory, and calls the "plan()"
98           function for you (one test for each function), so you can't have
99           already called "plan".
100
101           If @files is empty or not passed, the function finds all Perl
102           module files in the blib directory if it exists, or the lib
103           directory if not. A Perl module file is one that ends with .pm.
104
105           If you're testing a module, just make a t/00_compile.t:
106
107               use Test::More;
108               eval "use Test::Compile 0.09";
109               plan skip_all => "Test::Compile 0.09 required for testing compilation"
110                 if $@;
111               all_pm_files_ok();
112
113           Returns true if all Perl module files are ok, or false if any fail.
114
115           Or you could just let Module::Install::StandardTests do all the
116           work for you.
117
118       "all_pl_files_ok([@files])"
119           Checks all the files in @files for compilation. It runs
120           pl_file_ok() on each file, and calls the "plan()" function for you
121           (one test for each file), so you can't have already called "plan".
122
123           If @files is empty or not passed, the function uses all_pl_files()
124           to find scripts to test
125
126           If you're testing a module, just make a t/00_compile_scripts.t:
127
128               use Test::More;
129               eval "use Test::Compile 0.09";
130               plan skip_all => "Test::Compile 0.09 required for testing compilation"
131                 if $@;
132               all_pl_files_ok();
133
134           Returns true if all Perl module files are ok, or false if any fail.
135
136       "all_pm_files([@dirs])"
137           Returns a list of all the perl module files - that is, files ending
138           in .pm - in $dir and in directories below. If no directories are
139           passed, it defaults to blib if blib exists, or else lib if not.
140           Skips any files in "CVS" or ".svn" directories.
141
142           The order of the files returned is machine-dependent. If you want
143           them sorted, you'll have to sort them yourself.
144
145       "all_pl_files([@files/@dirs])"
146           Returns a list of all the perl script files - that is, files ending
147           in .pl or with no extension. Directory arguments are searched
148           recursively . If arguments are passed, it defaults to script if
149           script exists, or else bin if bin exists. Skips any files in "CVS"
150           or ".svn" directories.
151
152           The order of the files returned is machine-dependent. If you want
153           them sorted, you'll have to sort them yourself.
154

BUGS AND LIMITATIONS

156       No bugs have been reported.
157
158       Please report any bugs or feature requests through the web interface at
159       <http://rt.cpan.org>.
160

INSTALLATION

162       See perlmodinstall for information and options on installing Perl
163       modules.
164

AVAILABILITY

166       The latest version of this module is available from the Comprehensive
167       Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find
168       a CPAN site near you. Or see http://search.cpan.org/dist/Test-Compile/
169       <http://search.cpan.org/dist/Test-Compile/>.
170

AUTHORS

172       Sagar R. Shah "<srshah@cpan.org>"
173
174       Marcel Gruenauer, "<marcel@cpan.org>"
175

COPYRIGHT AND LICENSE

177       Copyright 2007-2009 by the authors.
178
179       This library is free software; you can redistribute it and/or modify it
180       under the same terms as Perl itself.
181