git.maemo.org Git - dh-make-perl/blob - dev/i386/libtest-perl-critic-perl/libtest-perl-critic-perl-1.01/README

   1 NAME
   2     Test::Perl::Critic - Use Perl::Critic in test programs
   3
   4 SYNOPSIS
   5     Test one file:
   6
   7       use Test::Perl::Critic;
   8       use Test::More tests => 1;
   9       critic_ok($file);
  10
  11     Or test all files in one or more directories:
  12
  13       use Test::Perl::Critic;
  14       all_critic_ok($dir_1, $dir_2, $dir_N );
  15
  16     Or test all files in a distribution:
  17
  18       use Test::Perl::Critic;
  19       all_critic_ok();
  20
  21     Recommended usage for CPAN distributions:
  22
  23       use strict;
  24       use warnings;
  25       use File::Spec;
  26       use Test::More;
  27       use English qw(-no_match_vars);
  28
  29       if ( not $ENV{TEST_AUTHOR} ) {
  30           my $msg = 'Author test.  Set $ENV{TEST_AUTHOR} to a true value to run.';
  31           plan( skip_all => $msg );
  32       }
  33
  34       eval { require Test::Perl::Critic; };
  35
  36       if ( $EVAL_ERROR ) {
  37          my $msg = 'Test::Perl::Critic required to criticise code';
  38          plan( skip_all => $msg );
  39       }
  40
  41       my $rcfile = File::Spec->catfile( 't', 'perlcriticrc' );
  42       Test::Perl::Critic->import( -profile => $rcfile );
  43       all_critic_ok();
  44
  45 DESCRIPTION
  46     Test::Perl::Critic wraps the Perl::Critic engine in a convenient
  47     subroutine suitable for test programs written using the Test::More
  48     framework. This makes it easy to integrate coding-standards enforcement
  49     into the build process. For ultimate convenience (at the expense of some
  50     flexibility), see the criticism pragma.
  51
  52     If you'd like to try Perl::Critic without installing anything, there is
  53     a web-service available at <http://perlcritic.com>. The web-service does
  54     not yet support all the configuration features that are available in the
  55     native Perl::Critic API, but it should give you a good idea of what it
  56     does. You can also invoke the perlcritic web-service from the command
  57     line by doing an HTTP-post, such as one of these:
  58
  59       $> POST http://perlcritic.com/perl/critic.pl < MyModule.pm
  60       $> lwp-request -m POST http://perlcritic.com/perl/critic.pl < MyModule.pm
  61       $> wget -q -O - --post-file=MyModule.pm http://perlcritic.com/perl/critic.pl
  62
  63     Please note that the perlcritic web-service is still alpha code. The URL
  64     and interface to the service are subject to change.
  65
  66 SUBROUTINES
  67     critic_ok( $FILE [, $TEST_NAME ] )
  68             Okays the test if Perl::Critic does not find any violations in
  69             $FILE. If it does, the violations will be reported in the test
  70             diagnostics. The optional second argument is the name of test,
  71             which defaults to "Perl::Critic test for $FILE".
  72
  73             If you use this form, you should emit your own Test::More plan
  74             first.
  75
  76     all_critic_ok( [ @DIRECTORIES ] )
  77             Runs "critic_ok()" for all Perl files beneath the given list of
  78             @DIRECTORIES. If @DIRECTORIES is empty or not given, this
  79             function tries to find all Perl files in the blib/ directory. If
  80             the blib/ directory does not exist, then it tries the lib/
  81             directory. Returns true if all files are okay, or false if any
  82             file fails.
  83
  84             This subroutine emits its own Test::More plan, so you do not
  85             need to specify an expected number of tests yourself.
  86
  87     all_code_files ( [@DIRECTORIES] )
  88             DEPRECATED: Use the "all_perl_files" subroutine that is exported
  89             by Perl::Critic::Utils instead.
  90
  91             Returns a list of all the Perl files found beneath each
  92             DIRECTORY, If @DIRECTORIES is an empty list, defaults to blib/.
  93             If blib/ does not exist, it tries lib/. Skips any files in CVS
  94             or Subversion directories.
  95
  96             A Perl file is:
  97
  98             * Any file that ends in .PL, .pl, .pm, or .t
  99             * Any file that has a first line with a shebang containing
 100             'perl'
 101
 102 CONFIGURATION
 103     Perl::Critic is highly configurable. By default, Test::Perl::Critic
 104     invokes Perl::Critic with it's default configuration. But if you have
 105     developed your code against a custom Perl::Critic configuration, you
 106     will want to configure Test::Perl::Critic to do the same.
 107
 108     Any arguments given to the "use" pragma will be passed into the
 109     Perl::Critic constructor. So if you have developed your code using a
 110     custom ~/.perlcriticrc file, you can direct Test::Perl::Critic to use a
 111     custom file too.
 112
 113       use Test::Perl::Critic (-profile => 't/perlcriticrc');
 114       all_critic_ok();
 115
 116     Now place a copy of your own ~/.perlcriticrc file in the distribution as
 117     t/perlcriticrc. Then, "critic_ok()" will be run on all Perl files in
 118     this distribution using this same Perl::Critic configuration. See the
 119     Perl::Critic documentation for details on the .perlcriticrc file format.
 120
 121     Any argument that is supported by the Perl::Critic constructor can be
 122     passed through this interface. For example, you can also set the minimum
 123     severity level, or include & exclude specific policies like this:
 124
 125       use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
 126       all_critic_ok();
 127
 128     See the Perl::Critic documentation for complete details on it's options
 129     and arguments.
 130
 131 DIAGNOSTIC DETAILS
 132     By default, Test::Perl::Critic displays basic information about each
 133     Policy violation in the diagnostic output of the test. You can customize
 134     the format and content of this information by using the "-verbose"
 135     option. This behaves exactly like the "-verbose" switch on the
 136     perlcritic program. For example:
 137
 138       use Test::Perl::Critic (-verbose => 6);
 139
 140       #or...
 141
 142       use Test::Perl::Critic (-verbose => '%f: %m at %l');
 143
 144     If given a number, Test::Perl::Critic reports violations using one of
 145     the predefined formats described below. If given a string, it is
 146     interpreted to be an actual format specification. If the "-verbose"
 147     option is not specified, it defaults to 3.
 148
 149         Verbosity     Format Specification
 150         -----------   -------------------------------------------------------------
 151          1            "%f:%l:%c:%m\n",
 152          2            "%f: (%l:%c) %m\n",
 153          3            "%m at %f line %l\n",
 154          4            "%m at line %l, column %c.  %e.  (Severity: %s)\n",
 155          5            "%f: %m at line %l, column %c.  %e.  (Severity: %s)\n",
 156          6            "%m at line %l, near '%r'.  (Severity: %s)\n",
 157          7            "%f: %m at line %l near '%r'.  (Severity: %s)\n",
 158          8            "[%p] %m at line %l, column %c.  (Severity: %s)\n",
 159          9            "[%p] %m at line %l, near '%r'.  (Severity: %s)\n",
 160         10            "%m at line %l, column %c.\n  %p (Severity: %s)\n%d\n",
 161         11            "%m at line %l, near '%r'.\n  %p (Severity: %s)\n%d\n"
 162
 163     Formats are a combination of literal and escape characters similar to
 164     the way "sprintf" works. See String::Format for a full explanation of
 165     the formatting capabilities. Valid escape characters are:
 166
 167         Escape    Meaning
 168         -------   ----------------------------------------------------------------
 169         %c        Column number where the violation occurred
 170         %d        Full diagnostic discussion of the violation
 171         %e        Explanation of violation or page numbers in PBP
 172         %f        Name of the file where the violation occurred.
 173         %l        Line number where the violation occurred
 174         %m        Brief description of the violation
 175         %P        Name of the Policy module that created the violation
 176         %p        Name of the Policy without the Perl::Critic::Policy:: prefix
 177         %r        The string of source code that caused the violation
 178         %s        The severity level of the violation
 179
 180 CAVEATS
 181     Despite the convenience of using a test script to enforce your coding
 182     standards, there are some inherent risks when distributing those tests
 183     to others. Since you don't know which version of Perl::Critic the
 184     end-user has and whether they have installed any additional Policy
 185     modules, you can't really be sure that your code will pass the
 186     Test::Perl::Critic tests on another machine.
 187
 188     For these reasons, we strongly advise you to make your perlcritic tests
 189     optional, or exclude them from the distribution entirely.
 190
 191     The recommended usage in the "SYNOPSIS" section illustrates one way to
 192     make your perlcritic.t test optional. Also, you should not list
 193     Test::Perl::Critic as a requirement in your build script. These tests
 194     are only relevant to the author and should not be a prerequisite for
 195     end-use.
 196
 197     See
 198     <http://www.chrisdolan.net/talk/index.php/2005/11/14/private-regression-
 199     tests/> for an interesting discussion about Test::Perl::Critic and other
 200     types of author-only regression tests.
 201
 202 EXPORTS
 203       critic_ok()
 204       all_critic_ok()
 205
 206 PERFORMANCE HACKS
 207     If you want a small performance boost, you can tell PPI to cache results
 208     from previous parsing runs. Most of the processing time is in
 209     Perl::Critic, not PPI, so the speedup is not huge (only about 20%).
 210     Nonetheless, if your distribution is large, it's worth the effort.
 211
 212     Add a block of code like the following to your test program, probably
 213     just before the call to "all_critic_ok()". Be sure to adjust the path to
 214     the temp directory appropriately for your system.
 215
 216         use File::Spec;
 217         my $cache_path = File::Spec->catdir(File::Spec->tmpdir,
 218                                             "test-perl-critic-cache-$ENV{USER}");
 219         if (!-d $cache_path) {
 220            mkdir $cache_path, oct 700;
 221         }
 222         require PPI::Cache;
 223         PPI::Cache->import(path => $cache_path);
 224
 225     We recommend that you do NOT use this technique for tests that will go
 226     out to end-users. They're probably going to only run the tests once, so
 227     they will not see the benefit of the caching but will still have files
 228     stored in their temp directory.
 229
 230 BUGS
 231     If you find any bugs, please submit them to
 232     <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Perl-Critic>. Thanks.
 233
 234 SEE ALSO
 235     Module::Starter::PBP
 236
 237     Perl::Critic
 238
 239     Test::More
 240
 241 CREDITS
 242     Andy Lester, whose Test::Pod module provided most of the code and
 243     documentation for Test::Perl::Critic. Thanks, Andy.
 244
 245 AUTHOR
 246     Jeffrey Ryan Thalhammer <thaljef@cpan.org>
 247
 248 COPYRIGHT
 249     Copyright (c) 2005-2006 Jeffrey Ryan Thalhammer. All rights reserved.
 250
 251     This program is free software; you can redistribute it and/or modify it
 252     under the same terms as Perl itself. The full text of this license can
 253     be found in the LICENSE file included with this module.
 254