1Test::Perl::Critic(3) User Contributed Perl DocumentationTest::Perl::Critic(3)
2
3
4

NAME

6       Test::Perl::Critic - Use Perl::Critic in test programs
7

SYNOPSIS

9       Test one file:
10
11         use Test::Perl::Critic;
12         use Test::More tests => 1;
13         critic_ok($file);
14
15       Or test all files in one or more directories:
16
17         use Test::Perl::Critic;
18         all_critic_ok($dir_1, $dir_2, $dir_N );
19
20       Or test all files in a distribution:
21
22         use Test::Perl::Critic;
23         all_critic_ok();
24
25       Recommended usage for CPAN distributions:
26
27         use strict;
28         use warnings;
29         use File::Spec;
30         use Test::More;
31         use English qw(-no_match_vars);
32
33         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
38         eval { require Test::Perl::Critic; };
39
40         if ( $EVAL_ERROR ) {
41            my $msg = 'Test::Perl::Critic required to criticise code';
42            plan( skip_all => $msg );
43         }
44
45         my $rcfile = File::Spec->catfile( 't', 'perlcriticrc' );
46         Test::Perl::Critic->import( -profile => $rcfile );
47         all_critic_ok();
48

DESCRIPTION

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
56       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
60       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

SUBROUTINES

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 @FILES
71           is empty or not given, then the blib/ is used if it exists, and if
72           not, then lib/ is used. Returns true if all files are okay, or
73           false if any file fails.
74
75           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
80           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
84       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
90           If you use this form, you should load Test::More and emit your own
91           test plan first or call done_testing() afterwards.
92

CONFIGURATION

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
99       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
105         use Test::Perl::Critic (-profile => 't/perlcriticrc');
106         all_critic_ok();
107
108       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 in
110       this distribution using this same Perl::Critic configuration.  See the
111       Perl::Critic documentation for details on the .perlcriticrc file
112       format.
113
114       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
119         use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
120         all_critic_ok();
121
122       See the Perl::Critic documentation for complete details on its options
123       and arguments.
124

DIAGNOSTIC DETAILS

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
132         use Test::Perl::Critic (-verbose => 6);
133
134         #or...
135
136         use Test::Perl::Critic (-verbose => '%f: %m at %l');
137
138       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
143           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
157       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
161           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

CAVEATS

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
187       For these reasons, we strongly advise you to make your perlcritic tests
188       optional, or exclude them from the distribution entirely.
189
190       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
198       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

FOR Dist::Zilla USERS

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

EXPORTS

213         critic_ok()
214         all_critic_ok()
215

BUGS

217       If you find any bugs, please submit them to
218       <https://github.com/Perl-Critic/Test-Perl-Critic/issues>.  Thanks.
219

SEE ALSO

221       Module::Starter::PBP
222
223       Perl::Critic
224
225       Test::More
226

CREDITS

228       Andy Lester, whose Test::Pod module provided most of the code and
229       documentation for Test::Perl::Critic.  Thanks, Andy.
230

AUTHOR

232       Jeffrey Ryan Thalhammer <jeff@thaljef.org>
233
235       Copyright (c) 2005-2018 Jeffrey Ryan Thalhammer.
236
237       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.
240
241
242
243perl v5.36.0                      2023-01-20             Test::Perl::Critic(3)
Impressum