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, which allows you to clean your code
58 incrementally instead of all at once..
59 If you'd like to try Perl::Critic without installing anything, there is
61 a web-service available at <http://perlcritic.com>. The web-service
62 does not support all the configuration features that are available in
63 the native Perl::Critic API, but it should give you a good idea of what
64 Perl::Critic can do.
65
67 all_critic_ok( [ @FILES ] )
68 Runs "critic_ok()" for all Perl files in the list of @FILES. If a
69 file is actually a directory, then all Perl files beneath that
70 directory (recursively) will be run through "critic_ok()". If
71 @FILES is empty or not given, then the blib/ is used if it exists,
72 and if not, then lib/ is used. Returns true if all files are okay,
73 or false if any file fails.
74 This subroutine emits its own test plan, so you do not need to
76 specify the expected number of tests or call "done_testing()".
77 Therefore, "all_critic_ok" generally cannot be used in a test
78 script that includes other sorts of tests.
79 "all_critic_ok()" is also optimized to run tests in parallel over
81 multiple cores (if you have them) so it is usually better to call
82 this function than calling "critic_ok()" directly.
83 critic_ok( $FILE [, $TEST_NAME ] )
85 Okays the test if Perl::Critic does not find any violations in
86 $FILE. If it does, the violations will be reported in the test
87 diagnostics. The optional second argument is the name of test,
88 which defaults to "Perl::Critic test for $FILE".
89 If you use this form, you should load Test::More and emit your own
91 test plan first or call "done_testing()" afterwards.
92
94 Perl::Critic is highly configurable. By default, Test::Perl::Critic
95 invokes Perl::Critic with its default configuration. But if you have
96 developed your code against a custom Perl::Critic configuration, you
97 will want to configure Test::Perl::Critic to do the same.
98 Any arguments passed through the "use" pragma (or via
100 "Test::Perl::Critic->import()" )will be passed into the Perl::Critic
101 constructor. So if you have developed your code using a custom
102 ~/.perlcriticrc file, you can direct Test::Perl::Critic to use your
103 custom file too.
104 use Test::Perl::Critic (-profile => 't/perlcriticrc');
106 all_critic_ok();
107 Now place a copy of your own ~/.perlcriticrc file in the distribution
109 as t/perlcriticrc. Then, "critic_ok()" will be run on all Perl files
110 in this distribution using this same Perl::Critic configuration. See
111 the Perl::Critic documentation for details on the .perlcriticrc file
112 format.
113 Any argument that is supported by the Perl::Critic constructor can be
115 passed through this interface. For example, you can also set the
116 minimum severity level, or include & exclude specific policies like
117 this:
118 use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
120 all_critic_ok();
121 See the Perl::Critic documentation for complete details on its options
123 and arguments.
124
126 By default, Test::Perl::Critic displays basic information about each
127 Policy violation in the diagnostic output of the test. You can
128 customize the format and content of this information by using the
129 "-verbose" option. This behaves exactly like the "-verbose" switch on
130 the perlcritic program. For example:
131 use Test::Perl::Critic (-verbose => 6);
133 #or...
135 use Test::Perl::Critic (-verbose => '%f: %m at %l');
137 If given a number, Test::Perl::Critic reports violations using one of
139 the predefined formats described below. If given a string, it is
140 interpreted to be an actual format specification. If the "-verbose"
141 option is not specified, it defaults to 3.
142 Verbosity Format Specification
144 ----------- -------------------------------------------------------
145 1 "%f:%l:%c:%m\n",
146 2 "%f: (%l:%c) %m\n",
147 3 "%m at %f line %l\n",
148 4 "%m at line %l, column %c. %e. (Severity: %s)\n",
149 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\n",
150 6 "%m at line %l, near '%r'. (Severity: %s)\n",
151 7 "%f: %m at line %l near '%r'. (Severity: %s)\n",
152 8 "[%p] %m at line %l, column %c. (Severity: %s)\n",
153 9 "[%p] %m at line %l, near '%r'. (Severity: %s)\n",
154 10 "%m at line %l, column %c.\n %p (Severity: %s)\n%d\n",
155 11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n"
156 Formats are a combination of literal and escape characters similar to
158 the way "sprintf" works. See String::Format for a full explanation of
159 the formatting capabilities. Valid escape characters are:
160 Escape Meaning
162 ------- ----------------------------------------------------------------
163 %c Column number where the violation occurred
164 %d Full diagnostic discussion of the violation (DESCRIPTION in POD)
165 %e Explanation of violation or page numbers in PBP
166 %F Just the name of the logical file where the violation occurred.
167 %f Path to the logical file where the violation occurred.
168 %G Just the name of the physical file where the violation occurred.
169 %g Path to the physical file where the violation occurred.
170 %l Logical line number where the violation occurred
171 %L Physical line number where the violation occurred
172 %m Brief description of the violation
173 %P Full name of the Policy module that created the violation
174 %p Name of the Policy without the Perl::Critic::Policy:: prefix
175 %r The string of source code that caused the violation
176 %C The class of the PPI::Element that caused the violation
177 %s The severity level of the violation
178
180 Despite the convenience of using a test script to enforce your coding
181 standards, there are some inherent risks when distributing those tests
182 to others. Since you don't know which version of Perl::Critic the end-
183 user has and whether they have installed any additional Policy modules,
184 you can't really be sure that your code will pass the
185 Test::Perl::Critic tests on another machine.
186 For these reasons, we strongly advise you to make your perlcritic tests
188 optional, or exclude them from the distribution entirely.
189 The recommended usage in the "SYNOPSIS" section illustrates one way to
191 make your perlcritic.t test optional. Another option is to put
192 perlcritic.t and other author-only tests in a separate directory (xt/
193 seems to be common), and then use a custom build action when you want
194 to run them. Also, you should not list Test::Perl::Critic as a
195 requirement in your build script. These tests are only relevant to the
196 author and should not be a prerequisite for end-use.
197 See <http://chrisdolan.net/talk/2005/11/14/private-regression-tests/>
199 for an interesting discussion about Test::Perl::Critic and other types
200 of author-only regression tests.
201
203 If you use Test::Perl::Critic with Dist::Zilla, beware that some DZ
204 plugins may mutate your code in ways that are not compliant with your
205 Perl::Critic rules. In particular, the standard
206 Dist::Zilla::Plugin::PkgVersion will inject a $VERSION declaration at
207 the top of the file, which will violate
208 Perl::Critic::Policy::TestingAndDebugging::RequireUseStrict. One
209 solution is to use the Dist::Zilla::Plugin::OurPkgVersion which allows
210 you to control where the $VERSION declaration appears.
211
213 critic_ok()
214 all_critic_ok()
215
217 If you find any bugs, please submit them to
218 <https://github.com/Perl-Critic/Test-Perl-Critic/issues>. Thanks.
219
221 Module::Starter::PBP
222 Perl::Critic
224 Test::More
226
228 Andy Lester, whose Test::Pod module provided most of the code and
229 documentation for Test::Perl::Critic. Thanks, Andy.
230
232 Jeffrey Ryan Thalhammer <jeff@thaljef.org>
233
235 Copyright (c) 2005-2018 Jeffrey Ryan Thalhammer.
236 This program is free software; you can redistribute it and/or modify it
238 under the same terms as Perl itself. The full text of this license can
239 be found in the LICENSE file included with this module.
240perl v5.32.0 2020-07-28 Test::Perl::Critic(3)