1Test::Perl::Critic::ProUgsreerssCiovnet(r3i)buted Perl DToecsutm:e:nPteartli:o:nCritic::Progressive(3)
2
3
4

NAME

6       Test::Perl::Critic::Progressive - Gradually enforce coding standards.
7

SYNOPSIS

9       To test one or more files, and/or all files in one or more directories:
10
11         use Test::Perl::Critic::Progressive qw( progressive_critic_ok );
12         progressive_critic_ok($file1, $file2, $dir1, $dir2);
13
14       To test all Perl files in a distribution:
15
16         use Test::Perl::Critic::Progressive qw( progressive_critic_ok );
17         progressive_critic_ok();
18
19       Recommended usage for public CPAN distributions:
20
21         use strict;
22         use warnings;
23         use Test::More;
24
25         eval { require Test::Perl::Critic::Progressive };
26         plan skip_all => 'T::P::C::Progressive required for this test' if $@;
27
28         Test::Perl::Critic::Progressive::progressive_critic_ok();
29

DESCRIPTION

31       Applying coding standards to large amounts of legacy code is a daunting
32       task.  Often times, legacy code is so non-compliant that it seems
33       downright impossible.  But, if you consistently chip away at the
34       problem, you will eventually succeed!  Test::Perl::Critic::Progressive
35       uses the Perl::Critic engine to prevent further deterioration of your
36       code and gradually steer it towards conforming with your chosen coding
37       standards.
38
39       The most effective way to use Test::Perl::Critic::Progressive is as a
40       unit test that is run under a continuous-integration system like
41       CruiseControl or AntHill.  Each time a developer commits changes to the
42       code, this test will fail and the build will break unless it has the
43       same (or fewer) Perl::Critic violations than the last successful test.
44
45       See the "NOTES" for more details about how this test works.
46

SUBROUTINES

48       All of the following subroutines can be exported upon request.  Or you
49       can export all of them at once using the ':all' tag.
50
51       " progressive_critic_ok(@FILES [, @DIRECTORIES ]) "
52        progressive_critic_ok()
53           Uses Perl::Critic to analyze each of the given @FILES, and/or all
54           Perl files beneath the given list of @DIRECTORIES.  If no arguments
55           are given, it analyzes all the Perl files in the blib/ directory.
56           If the blib/ directory does not exist, then it tries the lib/,
57           bin/, script/, and scripts/ directory.  The results of the analysis
58           will be stored as .perlcritic-history in the same directory where
59           your test script is located.
60
61           The first time you run this test, it will always pass.  But on each
62           subsequent run, the test will pass only if the number of violations
63           found is less than or equal to the number of violations found
64           during the last passing test.  If it does pass, then the history
65           file will be updated with the new analysis results.  Once all the
66           violations are removed from the code, this test will always pass,
67           unless a new violation is introduced.
68
69           This subroutine emits its own Test::More plan, so you do not need
70           to specify an expected number of tests yourself.
71
72        get_history_file()
73        set_history_file($FILE)
74           These functions get or set the full path to the history file.  This
75           is where Test::Perl::Critic::Progressive will store the results of
76           each passing analysis.  If the $FILE does not exist, it will be
77           created anew.  The default is "$Bin/.perlcritic-history" where $Bin
78           is the directory that the calling test script is located in.
79
80        get_total_step_size()
81        set_total_step_size($INTEGER)
82           These functions get or set the minimum acceptable decrease in the
83           total number of violations between each test.  The default value is
84           zero, which means that you are not required to remove any
85           violations, but you are also not allowed to add any.  If you set
86           the step size to a positive number, the test will require you to
87           remove $INTEGER violations each time the test is run.  In this
88           case, the particular type of violation that you eliminate doesn't
89           matter.  The larger the step size, the faster you'll have to
90           eliminate violations.
91
92        get_step_size_per_policy()
93        set_step_size_per_policy(%ARGS)
94           These functions get or set the minimum acceptable decrease in the
95           number of violations of a specific policy between each test.  The
96           %ARGS should be "$POLICY_NAME => $INTEGER" pairs, like this:
97
98             my %step_sizes = (
99                'ValuesAndExpressions::ProhibitLeadingZeros'  =>  2,
100                'Variables::ProhibitConditionalDeclarations'  =>  1,
101                'InputOutput::ProhibitTwoArgOpen'             =>  3,
102             );
103
104             set_step_size_per_policy( %step_sizes );
105             progressive_critic_ok();
106
107           The default step size for any given Policy is zero, which means
108           that you are not required to remove any violations, but you are
109           also not allowed to add any.  But if you wish to focus on
110           eliminating certain types of violations, then increasing the per-
111           policy step size will force you to decrease the number of
112           violations of that particular Policy, while ignoring other types of
113           violations.  The larger the step size, the faster you'll have to
114           eliminate violations.
115
116        get_critic_args()
117        set_critic_args(%ARGS)
118           These functions get or set the arguments given to Perl::Critic.  By
119           default, Test::Perl::Critic::Progressive invokes Perl::Critic with
120           its default configuration.  But if you have developed your code
121           against a custom Perl::Critic configuration, you will want to
122           configure this test to do the same.
123
124           Any %ARGS given to "set_critic_args" will be passed directly into
125           the Perl::Critic constructor.  So if you have developed your code
126           using a custom .perlcriticrc file, you can direct
127           Test::Perl::Critic::Progressive to use a custom file too.
128
129             use Test::Perl::Critic::Progressive ( ':all' );
130
131             set_critic_args(-profile => 't/perlcriticrc);
132             progressive_critic_ok();
133
134           Now place a copy of your own .perlcriticrc file in the distribution
135           as t/perlcriticrc.  Now, "progressive_critic_ok" will use this same
136           Perl::Critic configuration.  See the Perl::Critic documentation for
137           details on the .perlcriticrc file format.
138
139           Any argument that is supported by the Perl::Critic constructor can
140           be passed through this interface.  For example, you can also set
141           the minimum severity level, or include & exclude specific policies
142           like this:
143
144             use Test::Perl::Critic::Progressive ( ':all' );
145
146             set_critic_args( -severity => 2, -exclude => ['MixedCaseVars'] );
147             progressive_critic_ok();
148
149           See the Perl::Critic documentation for complete details on its
150           options and arguments.
151

NOTES

153       The test is evaluated in two ways. First, the number of violations for
154       each Policy must be less than or equal to the number of the violations
155       found during the last passing test, minus the step size for that
156       Policy.  Second, the total number of violations must be less than or
157       equal the total number of violations found during the last passing
158       test, minus the total step size.  This prevents you from simply
159       substituting one kind of violation for another.
160
161       You can use the total step size and the per-policy step size at the
162       same time.  For example, you can set the total step size to 5, and set
163       the per-policy step size for the
164       "TestingAndDebugging::RequireStrictures" Policy to 3.  In which case,
165       you'll have to remove 5 violations between each test, but 3 of them
166       must be violations of "TestingAndDebugging::RequireStrictures".
167
168       Over time, you'll probably add new Policies to your Perl::Critic setup.
169       When Test::Perl::Critic::Progressive uses a Policy for the first time,
170       any newly discovered violations of that Policy will not be considered
171       in the test.  However, they will be considered in subsequent tests.
172
173       If you are building a CPAN distribution, you'll want to add
174       ^t/.perlcritic-history$ to the MANIFEST.SKIP file.  And if you are
175       using a revision control system like CVS or Subversion, you'll probably
176       want to configure it to ignore the t/.perlcritic-history file as well.
177

BUGS

179       If you find any bugs, please submit them to
180       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Perl-Critic-Progressive>.
181       Thanks.
182

SEE ALSO

184       criticism
185
186       Perl::Critic
187
188       Test::Perl::Critic
189
190       <http://www.perlcritic.com>
191

AUTHOR

193       Jeffrey Ryan Thalhammer <thaljef@cpan.org>
194
196       Copyright (c) 2007-2008 Jeffrey Ryan Thalhammer.  All rights reserved.
197
198       This program is free software; you can redistribute it and/or modify it
199       under the same terms as Perl itself.  The full text of this license can
200       be found in the LICENSE file included with this module.
201
202
203
204perl v5.38.0                      2023-07-21Test::Perl::Critic::Progressive(3)
Impressum