| 1 |
NAME |
| 2 |
Test::Perl::Critic::Progressive - Gradually enforce coding standards. |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
To test one or more files, and/or all files in one or more directories: |
| 6 |
|
| 7 |
use Test::Perl::Critic::Progressive qw( progressive_critic_ok ); |
| 8 |
progressive_critic_ok($file1, $file2, $dir1, $dir2); |
| 9 |
|
| 10 |
To test all Perl files in a distribution: |
| 11 |
|
| 12 |
use Test::Perl::Critic::Progressive qw( progressive_critic_ok ); |
| 13 |
progressive_critic_ok(); |
| 14 |
|
| 15 |
Recommended usage for public CPAN distributions: |
| 16 |
|
| 17 |
use strict; |
| 18 |
use warnings; |
| 19 |
use Test::More; |
| 20 |
|
| 21 |
eval { require Test::Perl::Critic::Progressive }; |
| 22 |
plan skip_all => 'T::P::C::Progressive required for this test' if $@; |
| 23 |
|
| 24 |
Test::Perl::Critic::Progressive::progressive_critic_ok(); |
| 25 |
|
| 26 |
DESCRIPTION |
| 27 |
Applying coding standards to large amounts of legacy code is a daunting |
| 28 |
task. Often times, legacy code is so non-compliant that it seems |
| 29 |
downright impossible. But, if you consistently chip away at the problem, |
| 30 |
you will eventually succeed! Test::Perl::Critic::Progressive uses the |
| 31 |
Perl::Critic engine to prevent further deterioration of your code and |
| 32 |
gradually steer it towards conforming with your chosen coding standards. |
| 33 |
|
| 34 |
The most effective way to use Test::Perl::Critic::Progressive is as a |
| 35 |
unit test that is run under a continuous-integration system like |
| 36 |
CruiseControl or AntHill. Each time a developer commits changes to the |
| 37 |
code, this test will fail and the build will break unless it has the |
| 38 |
same (or fewer) Perl::Critic violations than the last successful test. |
| 39 |
|
| 40 |
See the "NOTES" for more details about how this test works. |
| 41 |
|
| 42 |
SUBROUTINES |
| 43 |
All of the following subroutines can be exported upon request. Or you |
| 44 |
can export all of them at once using the ':all' tag. |
| 45 |
|
| 46 |
" progressive_critic_ok(@FILES [, @DIRECTORIES ]) " |
| 47 |
" progressive_critic_ok() " |
| 48 |
Uses Perl::Critic to analyze each of the given @FILES, and/or all |
| 49 |
Perl files beneath the given list of @DIRECTORIES. If no arguments |
| 50 |
are given, it analyzes all the Perl files in the blib/ directory. If |
| 51 |
the blib/ directory does not exist, then it tries the lib/, bin/, |
| 52 |
script/, and scripts/ directory. The results of the analysis will be |
| 53 |
stored as .perlcritic-history in the same directory where your test |
| 54 |
script is located. |
| 55 |
|
| 56 |
The first time you run this test, it will always pass. But on each |
| 57 |
subsequent run, the test will pass only if the number of violations |
| 58 |
found is less than or equal to the number of violations found during |
| 59 |
the last passing test. If it does pass, then the history file will |
| 60 |
be updated with the new analysis results. Once all the violations |
| 61 |
are removed from the code, this test will always pass, unless a new |
| 62 |
violation is introduced. |
| 63 |
|
| 64 |
This subroutine emits its own Test::More plan, so you do not need to |
| 65 |
specify an expected number of tests yourself. |
| 66 |
|
| 67 |
" get_history_file() " |
| 68 |
" set_history_file($FILE) " |
| 69 |
These functions get or set the full path to the history file. This |
| 70 |
is where Test::Perl::Critic::Progressive will store the results of |
| 71 |
each passing analysis. If the $FILE does not exist, it will be |
| 72 |
created anew. The default is "$Bin/.perlcritic-history" where $Bin |
| 73 |
is the directory that the calling test script is located in. |
| 74 |
|
| 75 |
" get_total_step_size() " |
| 76 |
" set_total_step_size($INTEGER) " |
| 77 |
These functions get or set the minimum acceptable decrease in the |
| 78 |
total number of violations between each test. The default value is |
| 79 |
zero, which means that you are not required to remove any |
| 80 |
violations, but you are also not allowed to add any. If you set the |
| 81 |
step size to a positive number, the test will require you to remove |
| 82 |
$INTEGER violations each time the test is run. In this case, the |
| 83 |
particular type of violation that you eliminate doesn't matter. The |
| 84 |
larger the step size, the faster you'll have to eliminate |
| 85 |
violations. |
| 86 |
|
| 87 |
" get_step_size_per_policy() " |
| 88 |
" set_step_size_per_policy(%ARGS) " |
| 89 |
These functions get or set the minimum acceptable decrease in the |
| 90 |
number of violations of a specific policy between each test. The |
| 91 |
%ARGS should be "$POLICY_NAME => $INTEGER" pairs, like this: |
| 92 |
|
| 93 |
my %step_sizes = ( |
| 94 |
'ValuesAndExpressions::ProhibitLeadingZeros' => 2, |
| 95 |
'Variables::ProhibitConditionalDeclarations' => 1, |
| 96 |
'InputOutput::ProhibitTwoArgOpen' => 3, |
| 97 |
); |
| 98 |
|
| 99 |
set_step_size_per_policy( %step_sizes ); |
| 100 |
progressive_critic_ok(); |
| 101 |
|
| 102 |
The default step size for any given Policy is zero, which means that |
| 103 |
you are not required to remove any violations, but you are also not |
| 104 |
allowed to add any. But if you wish to focus on eliminating certain |
| 105 |
types of violations, then increasing the per-policy step size will |
| 106 |
force you to decrease the number of violations of that particular |
| 107 |
Policy, while ignoring other types of violations. The larger the |
| 108 |
step size, the faster you'll have to eliminate violations. |
| 109 |
|
| 110 |
" get_critic_args() " |
| 111 |
" set_critic_args(%ARGS) " |
| 112 |
These functions get or set the arguments given to Perl::Critic. By |
| 113 |
default, Test::Perl::Critic::Progressive invokes Perl::Critic with |
| 114 |
its default configuration. But if you have developed your code |
| 115 |
against a custom Perl::Critic configuration, you will want to |
| 116 |
configure this test to do the same. |
| 117 |
|
| 118 |
Any %ARGS given to "set_critic_args" will be passed directly into |
| 119 |
the Perl::Critic constructor. So if you have developed your code |
| 120 |
using a custom .perlcriticrc file, you can direct |
| 121 |
Test::Perl::Critic::Progressive to use a custom file too. |
| 122 |
|
| 123 |
use Test::Perl::Critic::Progressive ( ':all' ); |
| 124 |
|
| 125 |
set_critic_args(-profile => 't/perlcriticrc); |
| 126 |
progressive_critic_ok(); |
| 127 |
|
| 128 |
Now place a copy of your own .perlcriticrc file in the distribution |
| 129 |
as t/perlcriticrc. Now, "progressive_critic_ok" will use this same |
| 130 |
Perl::Critic configuration. See the Perl::Critic documentation for |
| 131 |
details on the .perlcriticrc file format. |
| 132 |
|
| 133 |
Any argument that is supported by the Perl::Critic constructor can |
| 134 |
be passed through this interface. For example, you can also set the |
| 135 |
minimum severity level, or include & exclude specific policies like |
| 136 |
this: |
| 137 |
|
| 138 |
use Test::Perl::Critic::Progressive ( ':all' ); |
| 139 |
|
| 140 |
set_critic_args( -severity => 2, -exclude => ['MixedCaseVars'] ); |
| 141 |
progressive_critic_ok(); |
| 142 |
|
| 143 |
See the Perl::Critic documentation for complete details on its |
| 144 |
options and arguments. |
| 145 |
|
| 146 |
NOTES |
| 147 |
The test is evaluated in two ways. First, the number of violations for |
| 148 |
each Policy must be less than or equal to the number of the violations |
| 149 |
found during the last passing test, minus the step size for that Policy. |
| 150 |
Second, the total number of violations must be less than or equal the |
| 151 |
total number of violations found during the last passing test, minus the |
| 152 |
total step size. This prevents you from simply substituting one kind of |
| 153 |
violation for another. |
| 154 |
|
| 155 |
You can use the total step size and the per-policy step size at the same |
| 156 |
time. For example, you can set the total step size to 5, and set the |
| 157 |
per-policy step size for the "TestingAndDebugging::RequireStrictures" |
| 158 |
Policy to 3. In which case, you'll have to remove 5 violations between |
| 159 |
each test, but 3 of them must be violations of |
| 160 |
"TestingAndDebugging::RequireStrictures". |
| 161 |
|
| 162 |
Over time, you'll probably add new Policies to your Perl::Critic setup. |
| 163 |
When Test::Perl::Critic::Progressive uses a Policy for the first time, |
| 164 |
any newly discovered violations of that Policy will not be considered in |
| 165 |
the test. However, they will be considered in subsequent tests. |
| 166 |
|
| 167 |
If you are building a CPAN distribution, you'll want to add |
| 168 |
^t/.perlcritic-history$ to the MANIFEST.SKIP file. And if you are using |
| 169 |
a revision control system like CVS or Subversion, you'll probably want |
| 170 |
to configure it to ignore the t/.perlcritic-history file as well. |
| 171 |
|
| 172 |
BUGS |
| 173 |
If you find any bugs, please submit them to |
| 174 |
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Test-Perl-Critic-Progressive>. |
| 175 |
Thanks. |
| 176 |
|
| 177 |
SEE ALSO |
| 178 |
criticism |
| 179 |
|
| 180 |
Perl::Critic |
| 181 |
|
| 182 |
Test::Perl::Critic |
| 183 |
|
| 184 |
<http://www.perlcritic.com> |
| 185 |
|
| 186 |
AUTHOR |
| 187 |
Jeffrey Ryan Thalhammer <[email protected]> |
| 188 |
|
| 189 |
COPYRIGHT |
| 190 |
Copyright (c) 2007-2008 Jeffrey Ryan Thalhammer. All rights reserved. |
| 191 |
|
| 192 |
This program is free software; you can redistribute it and/or modify it |
| 193 |
under the same terms as Perl itself. The full text of this license can |
| 194 |
be found in the LICENSE file included with this module. |
| 195 |
|