.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Test::Perl::Critic 3pm" .TH Test::Perl::Critic 3pm "2015-08-15" "perl v5.20.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::Perl::Critic \- Use Perl::Critic in test programs .SH "SYNOPSIS" .IX Header "SYNOPSIS" Test one file: .PP .Vb 3 \& use Test::Perl::Critic; \& use Test::More tests => 1; \& critic_ok($file); .Ve .PP Or test all files in one or more directories: .PP .Vb 2 \& use Test::Perl::Critic; \& all_critic_ok($dir_1, $dir_2, $dir_N ); .Ve .PP Or test all files in a distribution: .PP .Vb 2 \& use Test::Perl::Critic; \& all_critic_ok(); .Ve .PP Recommended usage for \s-1CPAN\s0 distributions: .PP .Vb 5 \& use strict; \& use warnings; \& use File::Spec; \& use Test::More; \& use English qw(\-no_match_vars); \& \& if ( not $ENV{TEST_AUTHOR} ) { \& my $msg = \*(AqAuthor test. Set $ENV{TEST_AUTHOR} to a true value to run.\*(Aq; \& plan( skip_all => $msg ); \& } \& \& eval { require Test::Perl::Critic; }; \& \& if ( $EVAL_ERROR ) { \& my $msg = \*(AqTest::Perl::Critic required to criticise code\*(Aq; \& plan( skip_all => $msg ); \& } \& \& my $rcfile = File::Spec\->catfile( \*(Aqt\*(Aq, \*(Aqperlcriticrc\*(Aq ); \& Test::Perl::Critic\->import( \-profile => $rcfile ); \& all_critic_ok(); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Test::Perl::Critic wraps the Perl::Critic engine in a convenient subroutine suitable for test programs written using the Test::More framework. This makes it easy to integrate coding-standards enforcement into the build process. For ultimate convenience (at the expense of some flexibility), see the criticism pragma. .PP If you have an large existing code base, you might prefer to use Test::Perl::Critic::Progressive, which allows you to clean your code incrementally instead of all at once.. .PP If you'd like to try Perl::Critic without installing anything, there is a web-service available at . The web-service does not support all the configuration features that are available in the native Perl::Critic \s-1API,\s0 but it should give you a good idea of what Perl::Critic can do. .SH "SUBROUTINES" .IX Header "SUBROUTINES" .ie n .IP "all_critic_ok( [ @FILES ] )" 4 .el .IP "all_critic_ok( [ \f(CW@FILES\fR ] )" 4 .IX Item "all_critic_ok( [ @FILES ] )" Runs \f(CW\*(C`critic_ok()\*(C'\fR for all Perl files in the list of \f(CW@FILES\fR. If a file is actually a directory, then all Perl files beneath that directory (recursively) will be run through \f(CW\*(C`critic_ok()\*(C'\fR. If \f(CW@FILES\fR is empty or not given, then the \&\fIblib/\fR is used if it exists, and if not, then \fIlib/\fR is used. Returns true if all files are okay, or false if any file fails. .Sp This subroutine emits its own test plan, so you do not need to specify the expected number of tests or call \f(CW\*(C`done_testing()\*(C'\fR. Therefore, \f(CW\*(C`all_critic_ok\*(C'\fR generally cannot be used in a test script that includes other sorts of tests. .Sp \&\fIall_critic_ok()\fR is also optimized to run tests in parallel over multiple cores (if you have them) so it is usually better to call this function than calling \&\fIcritic_ok()\fR directly. .ie n .IP "critic_ok( $FILE [, $TEST_NAME ] )" 4 .el .IP "critic_ok( \f(CW$FILE\fR [, \f(CW$TEST_NAME\fR ] )" 4 .IX Item "critic_ok( $FILE [, $TEST_NAME ] )" Okays the test if Perl::Critic does not find any violations in \f(CW$FILE\fR. If it does, the violations will be reported in the test diagnostics. The optional second argument is the name of test, which defaults to \*(L"Perl::Critic test for \&\f(CW$FILE\fR\*(R". .Sp If you use this form, you should load Test::More and emit your own test plan first or call \f(CW\*(C`done_testing()\*(C'\fR afterwards. .SH "CONFIGURATION" .IX Header "CONFIGURATION" Perl::Critic is highly configurable. By default, Test::Perl::Critic invokes Perl::Critic with its default configuration. But if you have developed your code against a custom Perl::Critic configuration, you will want to configure Test::Perl::Critic to do the same. .PP Any arguments passed through the \f(CW\*(C`use\*(C'\fR pragma (or via \f(CW\*(C`Test::Perl::Critic\->import()\*(C'\fR )will be passed into the Perl::Critic constructor. So if you have developed your code using a custom \&\fI~/.perlcriticrc\fR file, you can direct Test::Perl::Critic to use your custom file too. .PP .Vb 2 \& use Test::Perl::Critic (\-profile => \*(Aqt/perlcriticrc\*(Aq); \& all_critic_ok(); .Ve .PP Now place a copy of your own \fI~/.perlcriticrc\fR file in the distribution as \&\fIt/perlcriticrc\fR. Then, \f(CW\*(C`critic_ok()\*(C'\fR will be run on all Perl files in this distribution using this same Perl::Critic configuration. See the Perl::Critic documentation for details on the \fI.perlcriticrc\fR file format. .PP Any argument that is supported by the Perl::Critic constructor can be passed through this interface. For example, you can also set the minimum severity level, or include & exclude specific policies like this: .PP .Vb 2 \& use Test::Perl::Critic (\-severity => 2, \-exclude => [\*(AqRequireRcsKeywords\*(Aq]); \& all_critic_ok(); .Ve .PP See the Perl::Critic documentation for complete details on its options and arguments. .SH "DIAGNOSTIC DETAILS" .IX Header "DIAGNOSTIC DETAILS" By default, Test::Perl::Critic displays basic information about each Policy violation in the diagnostic output of the test. You can customize the format and content of this information by using the \f(CW\*(C`\-verbose\*(C'\fR option. This behaves exactly like the \f(CW\*(C`\-verbose\*(C'\fR switch on the \fIperlcritic\fR program. For example: .PP .Vb 1 \& use Test::Perl::Critic (\-verbose => 6); \& \& #or... \& \& use Test::Perl::Critic (\-verbose => \*(Aq%f: %m at %l\*(Aq); .Ve .PP If given a number, Test::Perl::Critic reports violations using one of the predefined formats described below. If given a string, it is interpreted to be an actual format specification. If the \f(CW\*(C`\-verbose\*(C'\fR option is not specified, it defaults to 3. .PP .Vb 10 \& Verbosity Format Specification \& \-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& 1 "%f:%l:%c:%m\en", \& 2 "%f: (%l:%c) %m\en", \& 3 "%m at %f line %l\en", \& 4 "%m at line %l, column %c. %e. (Severity: %s)\en", \& 5 "%f: %m at line %l, column %c. %e. (Severity: %s)\en", \& 6 "%m at line %l, near \*(Aq%r\*(Aq. (Severity: %s)\en", \& 7 "%f: %m at line %l near \*(Aq%r\*(Aq. (Severity: %s)\en", \& 8 "[%p] %m at line %l, column %c. (Severity: %s)\en", \& 9 "[%p] %m at line %l, near \*(Aq%r\*(Aq. (Severity: %s)\en", \& 10 "%m at line %l, column %c.\en %p (Severity: %s)\en%d\en", \& 11 "%m at line %l, near \*(Aq%r\*(Aq.\en %p (Severity: %s)\en%d\en" .Ve .PP Formats are a combination of literal and escape characters similar to the way \&\f(CW\*(C`sprintf\*(C'\fR works. See String::Format for a full explanation of the formatting capabilities. Valid escape characters are: .PP .Vb 10 \& Escape Meaning \& \-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \& %c Column number where the violation occurred \& %d Full diagnostic discussion of the violation (DESCRIPTION in POD) \& %e Explanation of violation or page numbers in PBP \& %F Just the name of the logical file where the violation occurred. \& %f Path to the logical file where the violation occurred. \& %G Just the name of the physical file where the violation occurred. \& %g Path to the physical file where the violation occurred. \& %l Logical line number where the violation occurred \& %L Physical line number where the violation occurred \& %m Brief description of the violation \& %P Full name of the Policy module that created the violation \& %p Name of the Policy without the Perl::Critic::Policy:: prefix \& %r The string of source code that caused the violation \& %C The class of the PPI::Element that caused the violation \& %s The severity level of the violation .Ve .SH "CAVEATS" .IX Header "CAVEATS" Despite the convenience of using a test script to enforce your coding standards, there are some inherent risks when distributing those tests to others. Since you don't know which version of Perl::Critic the end-user has and whether they have installed any additional Policy modules, you can't really be sure that your code will pass the Test::Perl::Critic tests on another machine. .PP \&\fBFor these reasons, we strongly advise you to make your perlcritic tests optional, or exclude them from the distribution entirely.\fR .PP The recommended usage in the \*(L"\s-1SYNOPSIS\*(R"\s0 section illustrates one way to make your \fIperlcritic.t\fR test optional. Another option is to put \fIperlcritic.t\fR and other author-only tests in a separate directory (\fIxt/\fR seems to be common), and then use a custom build action when you want to run them. Also, you should \fBnot\fR list Test::Perl::Critic as a requirement in your build script. These tests are only relevant to the author and should not be a prerequisite for end-use. .PP See for an interesting discussion about Test::Perl::Critic and other types of author-only regression tests. .SH "FOR Dist::Zilla USERS" .IX Header "FOR Dist::Zilla USERS" If you use Test::Perl::Critic with Dist::Zilla, beware that some \s-1DZ\s0 plugins may mutate your code in ways that are not compliant with your Perl::Critic rules. In particular, the standard Dist::Zilla::Plugin::PkgVersion will inject a \f(CW$VERSION\fR declaration at the top of the file, which will violate Perl::Critic::Policy::TestingAndDebughgin::RequireUseStrict. One solution is to use the Dist::Zilla::Plugin::OurPkgVersion which allows you to control where the \f(CW$VERSION\fR declaration appears. .SH "EXPORTS" .IX Header "EXPORTS" .Vb 2 \& critic_ok() \& all_critic_ok() .Ve .SH "BUGS" .IX Header "BUGS" If you find any bugs, please submit them to . Thanks. .SH "SEE ALSO" .IX Header "SEE ALSO" Module::Starter::PBP .PP Perl::Critic .PP Test::More .SH "CREDITS" .IX Header "CREDITS" Andy Lester, whose Test::Pod module provided most of the code and documentation for Test::Perl::Critic. Thanks, Andy. .SH "AUTHOR" .IX Header "AUTHOR" Jeffrey Ryan Thalhammer .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 2005\-2014 Jeffrey Ryan Thalhammer. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of this license can be found in the \s-1LICENSE\s0 file included with this module.