Perl::Critic::TestUtils - Utility functions for testing new Policies.
use Perl::Critic::TestUtils qw(critique pcritique fcritique);
my $code = '<<END_CODE';
package Foo::Bar;
$foo = frobulator();
$baz = $foo ** 2;
1;
END_CODE
# Critique code against all loaded policies...
my $perl_critic_config = { -severity => 2 };
my $violation_count = critique( \$code, $perl_critic_config);
# Critique code against one policy...
my $custom_policy = 'Miscellanea::ProhibitFrobulation'
my $violation_count = pcritique( $custom_policy, \$code );
# Critique code against one filename-related policy...
my $custom_policy = 'Modules::RequireFilenameMatchesPackage'
my $violation_count = fcritique( $custom_policy, \$code, 'Foo/Bar.pm' );
This module is used by Perl::Critic only for self-testing. It provides a few handy subroutines for testing new Perl::Critic::Policy modules. Look at the test scripts that ship with Perl::Critic for more examples of how to use these subroutines.
undef for the default). Returns the violations that occurred.
undef for the default). Returns the number of violations that occurred.
critique_with_violations(), but tests only a single policy instead of
the whole bunch.
critique(), but tests only a single policy instead of the whole bunch.
Like pcritique_with_violations(), but pretends that the code was loaded
from the specified filename. This is handy for testing policies like
Modules::RequireFilenameMatchesPackage which care about the filename that
the source derived from.
The $filename parameter must be a relative path, not absolute. The file
and all necessary subdirectories will be created via File::Temp and will be
automatically deleted.
Like pcritique(), but pretends that the code was loaded from the specified
filename. This is handy for testing policies like
Modules::RequireFilenameMatchesPackage which care about the filename that
the source derived from.
The $filename parameter must be a relative path, not absolute. The file
and all necessary subdirectories will be created via File::Temp and will be
automatically deleted.
Modules::RequireEndWithOne. The inner
hash specifies a single test to be handed to pcritique() or fcritique(),
including the code string, test name, etc. See below for the syntax of 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 evaled and passed to pcritique(),
so be careful.
Note that nowhere within the .run file itself do you specify the policy that you're testing. That's implicit within the filename.
Test that we have a t/*/*.run for each lib/*/*.pm
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?
Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.
Copyright (c) 2005-2008 Chris Dolan. 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.