Perl::Critic::TestUtils(3)
NAME
Perl::Critic::TestUtils - Utility functions for testing new Policies.
INTERFACE SUPPORT
This is considered to be a public module. Any changes to its interface
will go through a deprecation cycle.
SYNOPSIS
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' );
DESCRIPTION
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 programs that ship with Perl::Critic for more examples
of how to use these subroutines.
EXPORTS
assert_version( $version )
Asserts that the $version passed matches the version of
Perl::Critic.
block_perlcriticrc()
If a user has a ~/.perlcriticrc file, this can interfere with
testing. This handy method disables the search for that file --
simply call it at the top of your .t program. Note that this is
not easily reversible, but that should not matter.
critique_with_violations( $code_string_ref, $config_ref )
Test a block of code against the specified Perl::Critic::Config
instance (or "undef" for the default). Returns the violations that
occurred.
critique( $code_string_ref, $config_ref )
Test a block of code against the specified Perl::Critic::Config
instance (or "undef" for the default). Returns the number of
violations that occurred.
pcritique_with_violations( $policy_name, $code_string_ref, $config_ref
)
Like "critique_with_violations()", but tests only a single policy
instead of the whole bunch.
pcritique( $policy_name, $code_string_ref, $config_ref )
Like "critique()", but tests only a single policy instead of the
whole bunch.
fcritique_with_violations( $policy_name, $code_string_ref, $filename,
$config_ref )
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.
fcritique( $policy_name, $code_string_ref, $filename, $config_ref )
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.
subtests_in_tree( $dir )
Searches the specified directory recursively for .run files. Each
one found is parsed and a hash-of-list-of-hashes is returned. The
outer hash is keyed on policy short name, like
"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.
should_skip_author_tests()
Answers whether author tests should run.
get_author_test_skip_message()
Returns a string containing the message that should be emitted when
a test is skipped due to it being an author test when author tests
are not enabled.
starting_points_including_examples()
Returns a list of the directories contain code that needs to be
tested when it is desired that the examples be included.
bundled_policy_names()
Returns a list of Policy packages that come bundled with this
package. This functions by searching MANIFEST for
lib/Perl/Critic/Policy/*.pm and converts the results to package
names.
names_of_policies_willing_to_work( %configuration )
Returns a list of the packages of policies that are willing to
function on the current system using the specified configuration.
.run file information
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
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?
AUTHOR
Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.
COPYRIGHT
Copyright (c) 2005-2011 Chris Dolan.
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.28.2 2019-05-24 Perl::Critic::TestUtils(3)
perl-critic 1.134.0 - Generated Fri Jun 7 09:04:28 CDT 2019