Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Build.PL
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ my $builder = $class->new(
'Perl::Critic::Utils' => 1.105,
'Perl::Critic::Violation' => 1.105,
'strict' => 0,
'Test::Builder' => 0.88,
'Test2::API' => 0,
'warnings' => 0,
},

Expand Down
1 change: 1 addition & 0 deletions Changes
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[NEXT]
Convert to Test2::API instead of Test::Builder.

Now requires Test::Builder~0.88 or later to support the done_testing()
method. This fixes GH #2.
Expand Down
2 changes: 1 addition & 1 deletion META.json
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"Perl::Critic" : "1.105",
"Perl::Critic::Utils" : "1.105",
"Perl::Critic::Violation" : "1.105",
"Test::Builder" : "0.88",
"Test2::API" : "0",
"strict" : "0",
"warnings" : "0"
}
Expand Down
2 changes: 1 addition & 1 deletion META.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ requires:
Perl::Critic: '1.105'
Perl::Critic::Utils: '1.105'
Perl::Critic::Violation: '1.105'
Test::Builder: '0.88'
Test2::API: '0'
strict: '0'
warnings: '0'
resources:
Expand Down
127 changes: 74 additions & 53 deletions README
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
NAME

Test::Perl::Critic - Use Perl::Critic in test programs

SYNOPSIS

Test one file:

use Test::Perl::Critic;
Expand All @@ -25,90 +27,98 @@ SYNOPSIS
use File::Spec;
use Test::More;
use English qw(-no_match_vars);

if ( not $ENV{TEST_AUTHOR} ) {
my $msg = 'Author test. Set $ENV{TEST_AUTHOR} to a true value to run.';
plan( skip_all => $msg );
}

eval { require Test::Perl::Critic; };

if ( $EVAL_ERROR ) {
my $msg = 'Test::Perl::Critic required to criticise code';
plan( skip_all => $msg );
}

my $rcfile = File::Spec->catfile( 't', 'perlcriticrc' );
Test::Perl::Critic->import( -profile => $rcfile );
all_critic_ok();

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.
subroutine suitable for test programs written using the
Test::More/Test2 frameworks. 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.

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..

If you'd like to try Perl::Critic without installing anything, there is
a web-service available at <http://perlcritic.com>. The web-service does
a web-service available at http://perlcritic.com. The web-service does
not support all the configuration features that are available in the
native Perl::Critic API, but it should give you a good idea of what
Perl::Critic can do.

SUBROUTINES

all_critic_ok( [ @FILES ] )
Runs "critic_ok()" for all Perl files in the list of @FILES. If a
file is actually a directory, then all Perl files beneath that
directory (recursively) will be run through "critic_ok()". If @FILES
is empty or not given, then the blib/ is used if it exists, and if
not, then lib/ is used. Returns true if all files are okay, or false
if any file fails.

This subroutine emits its own test plan, so you do not need to
specify the expected number of tests or call "done_testing()".
Therefore, "all_critic_ok" generally cannot be used in a test script
that includes other sorts of tests.

"all_critic_ok()" 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 "critic_ok()" directly.

Runs critic_ok() for all Perl files in the list of @FILES. If a file
is actually a directory, then all Perl files beneath that directory
(recursively) will be run through critic_ok(). If @FILES is empty or
not given, then the blib/ is used if it exists, and if not, then lib/
is used. Returns true if all files are okay, or false if any file
fails.

This subroutine emits its own test plan, so you do not need to
specify the expected number of tests or call done_testing().
Therefore, all_critic_ok generally cannot be used in a test script
that includes other sorts of tests.

all_critic_ok() 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 critic_ok() directly.

critic_ok( $FILE [, $TEST_NAME ] )
Okays the test if Perl::Critic does not find any violations in
$FILE. If it does, the violations will be reported in the test
diagnostics. The optional second argument is the name of test, which
defaults to "Perl::Critic test for $FILE".

If you use this form, you should load Test::More and emit your own
test plan first or call "done_testing()" afterwards.
Okays the test if Perl::Critic does not find any violations in $FILE.
If it does, the violations will be reported in the test diagnostics.
The optional second argument is the name of test, which defaults to
"Perl::Critic test for $FILE".

If you use this form, you should load Test::More/Test2::V0 and emit
your own test plan first or call done_testing() afterwards.

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.

Any arguments passed through the "use" pragma (or via
"Test::Perl::Critic->import()" )will be passed into the Perl::Critic
Any arguments passed through the use pragma (or via
Test::Perl::Critic->import() )will be passed into the Perl::Critic
constructor. So if you have developed your code using a custom
~/.perlcriticrc file, you can direct Test::Perl::Critic to use your
custom file too.

use Test::Perl::Critic (-profile => 't/perlcriticrc');
all_critic_ok();

Now place a copy of your own ~/.perlcriticrc file in the distribution as
t/perlcriticrc. Then, "critic_ok()" will be run on all Perl files in
Now place a copy of your own ~/.perlcriticrc file in the distribution
as t/perlcriticrc. Then, critic_ok() 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 .perlcriticrc file format.
Perl::Critic documentation for details on the .perlcriticrc file
format.

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:
passed through this interface. For example, you can also set the
minimum severity level, or include & exclude specific policies like
this:

use Test::Perl::Critic (-severity => 2, -exclude => ['RequireRcsKeywords']);
all_critic_ok();
Expand All @@ -117,21 +127,22 @@ CONFIGURATION
and arguments.

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 "-verbose"
option. This behaves exactly like the "-verbose" switch on the
Policy violation in the diagnostic output of the test. You can
customize the format and content of this information by using the
-verbose option. This behaves exactly like the -verbose switch on the
perlcritic program. For example:

use Test::Perl::Critic (-verbose => 6);

#or...

use Test::Perl::Critic (-verbose => '%f: %m at %l');

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 "-verbose"
interpreted to be an actual format specification. If the -verbose
option is not specified, it defaults to 3.

Verbosity Format Specification
Expand All @@ -149,8 +160,8 @@ DIAGNOSTIC DETAILS
11 "%m at line %l, near '%r'.\n %p (Severity: %s)\n%d\n"

Formats are a combination of literal and escape characters similar to
the way "sprintf" works. See String::Format for a full explanation of
the formatting capabilities. Valid escape characters are:
the way sprintf works. See String::Format for a full explanation of the
formatting capabilities. Valid escape characters are:

Escape Meaning
------- ----------------------------------------------------------------
Expand All @@ -171,6 +182,7 @@ DIAGNOSTIC DETAILS
%s The severity level of the violation

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
Expand All @@ -184,16 +196,17 @@ CAVEATS
The recommended usage in the "SYNOPSIS" section illustrates one way to
make your perlcritic.t test optional. Another option is to put
perlcritic.t and other author-only tests in a separate directory (xt/
seems to be common), and then use a custom build action when you want to
run them. Also, you should not 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.
seems to be common), and then use a custom build action when you want
to run them. Also, you should not 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.

See <http://chrisdolan.net/talk/2005/11/14/private-regression-tests/>
for an interesting discussion about Test::Perl::Critic and other types
of author-only regression tests.
See http://chrisdolan.net/talk/2005/11/14/private-regression-tests/ for
an interesting discussion about Test::Perl::Critic and other types of
author-only regression tests.

FOR Dist::Zilla USERS

If you use Test::Perl::Critic with Dist::Zilla, beware that some DZ
plugins may mutate your code in ways that are not compliant with your
Perl::Critic rules. In particular, the standard
Expand All @@ -204,28 +217,36 @@ FOR Dist::Zilla USERS
you to control where the $VERSION declaration appears.

EXPORTS

critic_ok()
all_critic_ok()

BUGS

If you find any bugs, please submit them to
<https://github.com/Perl-Critic/Test-Perl-Critic/issues>. Thanks.
https://github.com/Perl-Critic/Test-Perl-Critic/issues. Thanks.

SEE ALSO

Module::Starter::PBP

Perl::Critic

Test::More

Test2::Suite

CREDITS

Andy Lester, whose Test::Pod module provided most of the code and
documentation for Test::Perl::Critic. Thanks, Andy.

AUTHOR

Jeffrey Ryan Thalhammer <jeff@thaljef.org>

COPYRIGHT

Copyright (c) 2005-2017 Jeffrey Ryan Thalhammer.

This program is free software; you can redistribute it and/or modify it
Expand Down
Loading