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
51 subroutine suitable for test programs written using the Test::More
52 framework. This makes it easy to integrate coding-standards
53 enforcement into the build process. For ultimate convenience (at the
54 expense of some flexibility), see the criticism pragma.
55 If you have an large existing code base, you might prefer to use
57 Test::Perl::Critic::Progressive.
58 If you'd like to try Perl::Critic without installing anything, there is
60 a web-service available at <http://perlcritic.com>. The web-service
61 does not yet support all the configuration features that are available
62 in the native Perl::Critic API, but it should give you a good idea of
63 what it does. You can also invoke the perlcritic web-service from the
64 command line by doing an HTTP-post, such as one of these:
65 $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
67 $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
68 $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
69 Please note that the perlcritic web-service is still alpha code. The
71 URL and interface to the service are subject to change.
72
74 critic_ok( $FILE [, $TEST_NAME ] )
75 Okays the test if Perl::Critic does not find any violations in
76 $FILE. If it does, the violations will be reported in the test
77 diagnostics. The optional second argument is the name of test,
78 which defaults to "Perl::Critic test for $FILE".
79 If you use this form, you should emit your own Test::More plan
81 first.
82 all_critic_ok( [ @DIRECTORIES ] )
84 Runs "critic_ok()" for all Perl files beneath the given list of
85 @DIRECTORIES. If @DIRECTORIES is empty or not given, this function
86 tries to find all Perl files in the blib/ directory. If the blib/
87 directory does not exist, then it tries the lib/ directory.
88 Returns true if all files are okay, or false if any file fails.
89 This subroutine emits its own Test::More plan, so you do not need
91 to specify an expected number of tests yourself.
92 all_code_files ( [@DIRECTORIES] )
94 DEPRECATED: Use the "all_perl_files" subroutine that is exported by
95 Perl::Critic::Utils instead.
96 Returns a list of all the Perl files found beneath each DIRECTORY,
98 If @DIRECTORIES is an empty list, defaults to blib/. If blib/ does
99 not exist, it tries lib/. Skips any files in CVS or Subversion
100 directories.
101 A Perl file is:
103 · Any file that ends in .PL, .pl, .pm, or .t
105 · Any file that has a first line with a shebang containing 'perl'
107
109 Perl::Critic is highly configurable. By default, Test::Perl::Critic
110 invokes Perl::Critic with its default configuration. But if you have
111 developed your code against a custom Perl::Critic configuration, you
112 will want to configure Test::Perl::Critic to do the same.
113 Any arguments passed through the "use" pragma (or via
115 "Test::Perl::Critic->import()" )will be passed into the Perl::Critic
116 constructor. So if you have developed your code using a custom
117 ~/.perlcriticrc file, you can direct Test::Perl::Critic to use your
118 custom file too.
119 use Test::Perl::Critic (-profile => 't/perlcriticrc');
121 all_critic_ok();
122 Now place a copy of your own ~/.perlcriticrc file in the distribution
124 as t/perlcriticrc. Then, "critic_ok()" will be run on all Perl files
125 in this distribution using this same Perl::Critic configuration. See
126 the Perl::Critic documentation for details on the .perlcriticrc file
127 format.
128 Any argument that is supported by the Perl::Critic constructor can be
130 passed through this interface. For example, you can also set the
131 minimum severity level, or include & exclude specific policies like
132 this:
133 use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
135 all_critic_ok();
136 See the Perl::Critic documentation for complete details on its options
138 and arguments.
139
141 By default, Test::Perl::Critic displays basic information about each
142 Policy violation in the diagnostic output of the test. You can
143 customize the format and content of this information by using the
144 "-verbose" option. This behaves exactly like the "-verbose" switch on
145 the perlcritic program. For example:
146 use Test::Perl::Critic (-verbose => 6);
148 #or...
150 use Test::Perl::Critic (-verbose => '%f: %m at %l');
152 If given a number, Test::Perl::Critic reports violations using one of
154 the predefined formats described below. If given a string, it is
155 interpreted to be an actual format specification. If the "-verbose"
156 option is not specified, it defaults to 3.
157 Verbosity Format Specification
159 ----------- -------------------------------------------------------
160 1 "%f:%l:%c:%m\n",
161 2 "%f: (%l:%c) %m\n",
162 3 "%m at %f line %l\n",
163 4 "%m at line %l, column %c. %e. (Severity: %s)\n",
164 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n",
165 6 "%m at line %l, near '%r'. (Severity: %s)\n",
166 7 "%f: %m at line %l near '%r'. (Severity: %s)\n",
167 8 "[%p] %m at line %l, column %c. (Severity: %s)\n",
168 9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n",
169 10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n",
170 11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n"
171 Formats are a combination of literal and escape characters similar to
173 the way "sprintf" works. See String::Format for a full explanation of
174 the formatting capabilities. Valid escape characters are:
175 Escape Meaning
177 ------- ----------------------------------------------------------------
178 %c Column number where the violation occurred
179 %d Full diagnostic discussion of the violation (DESCRIPTION in POD)
180 %e Explanation of violation or page numbers in PBP
181 %F Just the name of the logical file where the violation occurred.
182 %f Path to the logical file where the violation occurred.
183 %G Just the name of the physical file where the violation occurred.
184 %g Path to the physical file where the violation occurred.
185 %l Logical line number where the violation occurred
186 %L Physical line number where the violation occurred
187 %m Brief description of the violation
188 %P Full name of the Policy module that created the violation
189 %p Name of the Policy without the Perl::Critic::Policy:: prefix
190 %r The string of source code that caused the violation
191 %C The class of the PPI::Element that caused the violation
192 %s The severity level of the violation
193
195 Despite the convenience of using a test script to enforce your coding
196 standards, there are some inherent risks when distributing those tests
197 to others. Since you don't know which version of Perl::Critic the end-
198 user has and whether they have installed any additional Policy modules,
199 you can't really be sure that your code will pass the
200 Test::Perl::Critic tests on another machine.
201 For these reasons, we strongly advise you to make your perlcritic tests
203 optional, or exclude them from the distribution entirely.
204 The recommended usage in the "SYNOPSIS" section illustrates one way to
206 make your perlcritic.t test optional. Another option is to put
207 perlcritic.t and other author-only tests in a separate directory (xt/
208 seems to be common), and then use a custom build action when you want
209 to run them. Also, you should not list Test::Perl::Critic as a
210 requirement in your build script. These tests are only relevant to the
211 author and should not be a prerequisite for end-use.
212 See
214 http://www.chrisdolan.net/talk/index.php/2005/11/14/private-regression-tests/
215 <http://www.chrisdolan.net/talk/index.php/2005/11/14/private-
216 regression-tests/> for an interesting discussion about
217 Test::Perl::Critic and other types of author-only regression tests.
218
220 critic_ok()
221 all_critic_ok()
222
224 If you want a small performance boost, you can tell PPI to cache
225 results from previous parsing runs. Most of the processing time is in
226 Perl::Critic, not PPI, so the speedup is not huge (only about 20%).
227 Nonetheless, if your distribution is large, it's worth the effort.
228 Add a block of code like the following to your test program, probably
230 just before the call to "all_critic_ok()". Be sure to adjust the path
231 to the temp directory appropriately for your system.
232 use File::Spec;
234 my $cache_path = File::Spec->catdir(File::Spec->tmpdir,
235 "test-perl-critic-cache-$ENV{USER}");
236 if (!-d $cache_path) {
237 mkdir $cache_path, oct 700;
238 }
239 require PPI::Cache;
240 PPI::Cache->import(path => $cache_path);
241 We recommend that you do NOT use this technique for tests that will go
243 out to end-users. They're probably going to only run the tests once,
244 so they will not see the benefit of the caching but will still have
245 files stored in their temp directory.
246
248 If you find any bugs, please submit them to
249 http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic
250 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
251
253 Module::Starter::PBP
254 Perl::Critic
256 Test::More
258
260 Andy Lester, whose Test::Pod module provided most of the code and
261 documentation for Test::Perl::Critic. Thanks, Andy.
262
264 Jeffrey Ryan Thalhammer <jeff@imaginative-software.com>
265
267 Copyright (c) 2005-2009 Imaginative Software Systems. All rights
268 reserved.
269 This program is free software; you can redistribute it and/or modify it
271 under the same terms as Perl itself. The full text of this license can
272 be found in the LICENSE file included with this module.
273perl v5.12.0 2010-05-06 Test::Perl::Critic(3)