Test::Perl::Critic::PoUser(Contributed Perl DocumTest::Perl::Critic::Policy(3)NAMETest::Perl::Critic::Policy - A framework for testing your custom
Policies
SYNOPSIS
use Test::Perl::Critic::Policy qw< all_policies_ok >;
# Assuming .run files are inside 't' directory...
all_policies_ok()
# Or if your .run files are in a different directory...
all_policies_ok( '-test-directory' => 'run' );
# And if you just want to run tests for some polices...
all_policies_ok( -policies => ['Some::Policy', 'Another::Policy'] );
# If you want your test program to accept short Policy names as
# command-line parameters...
#
# You can then test a single policy by running
# "perl -Ilib t/policy-test.t My::Policy".
my %args = @ARGV ? ( -policies => [ @ARGV ] ) : ();
all_policies_ok(%args);
DESCRIPTION
This module provides a framework for function-testing your custom
Perl::Critic::Policy modules. Policy testing usually involves feeding
it a string of Perl code and checking its behavior. In the old days,
those strings of Perl code were mixed directly in the test script.
That sucked.
NOTE: This module is alpha code -- interfaces and implementation are
subject to major changes. This module is an integral part of building
and testing Perl::Critic itself, but you should not write any code
against this module until it has stabilized.
IMPORTABLE SUBROUTINES
all_policies_ok('-test-directory' => $path, -policies =>
\@policy_names)
Loads all the *.run files beneath the "-test-directory" and runs
the tests. If "-test-directory" is not specified, it defaults to
t/. "-policies" is an optional reference to an array of shortened
Policy names. If "-policies" specified, only the tests for
Policies that match one of the "m/$POLICY_NAME/imx" will be run.
CREATING THE *.run FILES
Testing a policy follows a very simple pattern:
* Policy name
* Subtest name
* Optional parameters
* Number of failures expected
* Optional exception expected
* Optional filename for code
Each of the subtests for a policy is collected in a single .run file,
with test properties as comments in front of each code block that
describes how we expect Perl::Critic to react to the code. For
example, say you have a policy called Variables::ProhibitVowels:
(In file t/Variables/ProhibitVowels.run)
## name Basics
## failures 1
## cut
my $vrbl_nm = 'foo'; # Good, vowel-free name
my $wango = 12; # Bad, pronouncable name
## name Sometimes Y
## failures 1
## cut
my $yllw = 0; # "y" not a vowel here
my $rhythm = 12; # But here it is
These are called "subtests", and two are shown above. The beauty of
incorporating multiple subtests in a file is that the .run is itself a
(mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
color-coding still works, and it is much easier to work with the code
and the POD.
If you need to pass any configuration parameters for your subtest, do
so like this:
## parms { allow_y => '0' }
Note that all the values in this hash must be strings because that's
what Perl::Critic will hand you from a .perlcriticrc.
If it's a TODO subtest (probably because of some weird corner of PPI
that we exercised that Adam is getting around to fixing, right?), then
make a "##TODO" entry.
## TODO Should pass when PPI 1.xxx comes out
If the code is expected to trigger an exception in the policy, indicate
that like so:
## error 1
If you want to test the error message, mark it with "/.../" to indicate
a "like()" test:
## error /Can't load Foo::Bar/
If the policy you are testing cares about the filename of the code, you
can indicate that "fcritique" should be used like so (see "fcritique"
for more details):
## filename lib/Foo/Bar.pm
The value of "parms" will get "eval"ed and passed to "pcritique()", so
be careful.
In general, a subtest document runs from the "## cut" that starts it to
either the next "## name" or the end of the file. In very rare
circumstances you may need to end the test document earlier. A second
"## cut" will do this. The only known need for this is in
t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the
RCS keywords in the file footer from producing false positives or
negatives in the last test.
Note that nowhere within the .run file itself do you specify the policy
that you're testing. That's implicit within the filename.
BUGS AND CAVEATS AND TODO ITEMS
Add policy_ok() method for running subtests in just a single TODO file.
Can users mark this entire test as TODO or SKIP, using the normal
mechanisms?
Allow us to specify the nature of the failures, and which one. If
there are 15 lines of code, and six of them fail, how do we know
they're the right six?
Consolidate code from Perl::Critic::TestUtils and possibly deprecate
some functions there.
Write unit tests for this module.
Test that we have a t/*/*.run for each lib/*/*.pm
AUTHOR
Andy Lester, Jeffrey Ryan Thalhammer <thaljef@cpan.org>
COPYRIGHT
Copyright (c) 2009-2011 Andy Lester. All rights reserved.
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 LICENSE file included with this module.
perl v5.14.1 2011-07-22 Test::Perl::Critic::Policy(3)
