1Test::Perl::Critic::ProUgsreerssCiovnet(r3i)buted Perl DToecsutm:e:nPteartli:o:nCritic::Progressive(3)
2
6 Test::Perl::Critic::Progressive - Gradually enforce coding standards.
7
9 To test one or more files, and/or all files in one or more directories:
10 use Test::Perl::Critic::Progressive qw( progressive_critic_ok );
12 progressive_critic_ok($file1, $file2, $dir1, $dir2);
13 To test all Perl files in a distribution:
15 use Test::Perl::Critic::Progressive qw( progressive_critic_ok );
17 progressive_critic_ok();
18 Recommended usage for public CPAN distributions:
20 use strict;
22 use warnings;
23 use Test::More;
24 eval { require Test::Perl::Critic::Progressive };
26 plan skip_all => 'T::P::C::Progressive required for this test' if $@;
27 Test::Perl::Critic::Progressive::progressive_critic_ok();
29
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 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 See the "NOTES" for more details about how this test works.
46
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 " 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 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 This subroutine emits its own Test::More plan, so you do not need
70 to specify an expected number of tests yourself.
71 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 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 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 my %step_sizes = (
99 'ValuesAndExpressions::ProhibitLeadingZeros' => 2,
100 'Variables::ProhibitConditionalDeclarations' => 1,
101 'InputOutput::ProhibitTwoArgOpen' => 3,
102 );
103 set_step_size_per_policy( %step_sizes );
105 progressive_critic_ok();
106 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 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 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 use Test::Perl::Critic::Progressive ( ':all' );
130 set_critic_args(-profile => 't/perlcriticrc);
132 progressive_critic_ok();
133 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 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 use Test::Perl::Critic::Progressive ( ':all' );
145 set_critic_args( -severity => 2, -exclude => ['MixedCaseVars'] );
147 progressive_critic_ok();
148 See the Perl::Critic documentation for complete details on its
150 options and arguments.
151
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 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 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 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
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
184 criticism
185 Perl::Critic
187 Test::Perl::Critic
189 <http://www.perlcritic.com>
191
193 Jeffrey Ryan Thalhammer <thaljef@cpan.org>
194
196 Copyright (c) 2007-2008 Jeffrey Ryan Thalhammer. All rights reserved.
197 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.
201perl v5.38.0 2023-07-21Test::Perl::Critic::Progressive(3)