1Test::Perl::Critic(3) User Contributed Perl DocumentationTest::Perl::Critic(3)
2
6 Test::Perl::Critic - Use Perl::Critic in test programs
7
9 Test one file:
10 use Test::Perl::Critic;
12 use Test::More tests => 1;
13 critic_ok($file);
14 Or test all files in one or more directories:
16 use Test::Perl::Critic;
18 all_critic_ok($dir_1, $dir_2, $dir_N );
19 Or test all files in a distribution:
21 use Test::Perl::Critic;
23 all_critic_ok();
24 Recommended usage for CPAN distributions:
26 use strict;
28 use warnings;
29 use File::Spec;
30 use Test::More;
31 use English qw(-no_match_vars);
32 if ( not $ENV{TEST_AUTHOR} ) {
34 my $msg = 'Author test. Set $ENV{TEST_AUTHOR} to a true value to run.';
35 plan( skip_all => $msg );
36 }
37 eval { require Test::Perl::Critic; };
39 if ( $EVAL_ERROR ) {
41 my $msg = 'Test::Perl::Critic required to criticise code';
42 plan( skip_all => $msg );
43 }
44 my $rcfile = File::Spec->catfile( 't', 'perlcriticrc' );
46 Test::Perl::Critic->import( -profile => $rcfile );
47 all_critic_ok();
48
50 Test::Perl::Critic wraps the Perl::Critic engine in a convenient sub‐
51 routine suitable for test programs written using the Test::More frame‐
52 work. This makes it easy to integrate coding-standards enforcement
53 into the build process. For ultimate convenience (at the expense of
54 some flexibility), see the criticism pragma.
55 If you'd like to try Perl::Critic without installing anything, there is
57 a web-service available at <http://perlcritic.com>. The web-service
58 does not yet support all the configuration features that are available
59 in the native Perl::Critic API, but it should give you a good idea of
60 what it does. You can also invoke the perlcritic web-service from the
61 command line by doing an HTTP-post, such as one of these:
62 $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
64 $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
65 $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
66 Please note that the perlcritic web-service is still alpha code. The
68 URL and interface to the service are subject to change.
69
71 critic_ok( $FILE [, $TEST_NAME ] )
72 Okays the test if Perl::Critic does not find any violations in
73 $FILE. If it does, the violations will be reported in the test
74 diagnostics. The optional second argument is the name of test,
75 which defaults to "Perl::Critic test for $FILE".
76 If you use this form, you should emit your own Test::More plan
78 first.
79 all_critic_ok( [ @DIRECTORIES ] )
81 Runs "critic_ok()" for all Perl files beneath the given list of
82 @DIRECTORIES. If @DIRECTORIES is empty or not given, this
83 function tries to find all Perl files in the blib/ directory.
84 If the blib/ directory does not exist, then it tries the lib/
85 directory. Returns true if all files are okay, or false if any
86 file fails.
87 This subroutine emits its own Test::More plan, so you do not
89 need to specify an expected number of tests yourself.
90 all_code_files ( [@DIRECTORIES] )
92 DEPRECATED: Use the "all_perl_files" subroutine that is
93 exported by Perl::Critic::Utils instead.
94 Returns a list of all the Perl files found beneath each DIREC‐
96 TORY, If @DIRECTORIES is an empty list, defaults to blib/. If
97 blib/ does not exist, it tries lib/. Skips any files in CVS or
98 Subversion directories.
99 A Perl file is:
101 * Any file that ends in .PL, .pl, .pm, or .t
103 * Any file that has a first line with a shebang containing
104 'perl'
105
107 Perl::Critic is highly configurable. By default, Test::Perl::Critic
108 invokes Perl::Critic with it's default configuration. But if you have
109 developed your code against a custom Perl::Critic configuration, you
110 will want to configure Test::Perl::Critic to do the same.
111 Any arguments given to the "use" pragma will be passed into the
113 Perl::Critic constructor. So if you have developed your code using a
114 custom ~/.perlcriticrc file, you can direct Test::Perl::Critic to use a
115 custom file too.
116 use Test::Perl::Critic (-profile => 't/perlcriticrc');
118 all_critic_ok();
119 Now place a copy of your own ~/.perlcriticrc file in the distribution
121 as t/perlcriticrc. Then, "critic_ok()" will be run on all Perl files
122 in this distribution using this same Perl::Critic configuration. See
123 the Perl::Critic documentation for details on the .perlcriticrc file
124 format.
125 Any argument that is supported by the Perl::Critic constructor can be
127 passed through this interface. For example, you can also set the mini‐
128 mum severity level, or include & exclude specific policies like this:
129 use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
131 all_critic_ok();
132 See the Perl::Critic documentation for complete details on it's options
134 and arguments.
135
137 By default, Test::Perl::Critic displays basic information about each
138 Policy violation in the diagnostic output of the test. You can custom‐
139 ize the format and content of this information by using the "-verbose"
140 option. This behaves exactly like the "-verbose" switch on the perl‐
141 critic program. For example:
142 use Test::Perl::Critic (-verbose => 6);
144 #or...
146 use Test::Perl::Critic (-verbose => '%f: %m at %l');
148 If given a number, Test::Perl::Critic reports violations using one of
150 the predefined formats described below. If given a string, it is inter‐
151 preted to be an actual format specification. If the "-verbose" option
152 is not specified, it defaults to 3.
153 Verbosity Format Specification
155 ----------- -------------------------------------------------------------
156 1 "%f:%l:%c:%m\n",
157 2 "%f: (%l:%c) %m\n",
158 3 "%m at %f line %l\n",
159 4 "%m at line %l, column %c. %e. (Severity: %s)\n",
160 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n",
161 6 "%m at line %l, near '%r'. (Severity: %s)\n",
162 7 "%f: %m at line %l near '%r'. (Severity: %s)\n",
163 8 "[%p] %m at line %l, column %c. (Severity: %s)\n",
164 9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n",
165 10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n",
166 11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n"
167 Formats are a combination of literal and escape characters similar to
169 the way "sprintf" works. See String::Format for a full explanation of
170 the formatting capabilities. Valid escape characters are:
171 Escape Meaning
173 ------- ----------------------------------------------------------------
174 %c Column number where the violation occurred
175 %d Full diagnostic discussion of the violation
176 %e Explanation of violation or page numbers in PBP
177 %f Name of the file where the violation occurred.
178 %l Line number where the violation occurred
179 %m Brief description of the violation
180 %P Name of the Policy module that created the violation
181 %p Name of the Policy without the Perl::Critic::Policy:: prefix
182 %r The string of source code that caused the violation
183 %s The severity level of the violation
184
186 Despite the convenience of using a test script to enforce your coding
187 standards, there are some inherent risks when distributing those tests
188 to others. Since you don't know which version of Perl::Critic the end-
189 user has and whether they have installed any additional Policy modules,
190 you can't really be sure that your code will pass the
191 Test::Perl::Critic tests on another machine.
192 For these reasons, we strongly advise you to make your perlcritic tests
194 optional, or exclude them from the distribution entirely.
195 The recommended usage in the "SYNOPSIS" section illustrates one way to
197 make your perlcritic.t test optional. Also, you should not list
198 Test::Perl::Critic as a requirement in your build script. These tests
199 are only relevant to the author and should not be a prerequisite for
200 end-use.
201 See <http://www.chrisdolan.net/talk/index.php/2005/11/14/pri‐
203 vate-regression-tests/> for an interesting discussion about
204 Test::Perl::Critic and other types of author-only regression tests.
205
207 critic_ok()
208 all_critic_ok()
209
211 If you want a small performance boost, you can tell PPI to cache
212 results from previous parsing runs. Most of the processing time is in
213 Perl::Critic, not PPI, so the speedup is not huge (only about 20%).
214 Nonetheless, if your distribution is large, it's worth the effort.
215 Add a block of code like the following to your test program, probably
217 just before the call to "all_critic_ok()". Be sure to adjust the path
218 to the temp directory appropriately for your system.
219 use File::Spec;
221 my $cache_path = File::Spec->catdir(File::Spec->tmpdir,
222 "test-perl-critic-cache-$ENV{USER}");
223 if (!-d $cache_path) {
224 mkdir $cache_path, oct 700;
225 }
226 require PPI::Cache;
227 PPI::Cache->import(path => $cache_path);
228 We recommend that you do NOT use this technique for tests that will go
230 out to end-users. They're probably going to only run the tests once,
231 so they will not see the benefit of the caching but will still have
232 files stored in their temp directory.
233
235 If you find any bugs, please submit them to
236 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
237
239 Module::Starter::PBP
240 Perl::Critic
242 Test::More
244
246 Andy Lester, whose Test::Pod module provided most of the code and docu‐
247 mentation for Test::Perl::Critic. Thanks, Andy.
248
250 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
251
253 Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.
254 This program is free software; you can redistribute it and/or modify it
256 under the same terms as Perl itself. The full text of this license can
257 be found in the LICENSE file included with this module.
258perl v5.8.8 2007-01-26 Test::Perl::Critic(3)