1Perl::Critic::TestUtilsU(s3e)r Contributed Perl DocumentaPteiroln::Critic::TestUtils(3)
2
3
4

NAME

6       Perl::Critic::TestUtils - Utility functions for testing new Policies.
7

INTERFACE SUPPORT

9       This is considered to be a public module.  Any changes to its interface
10       will go through a deprecation cycle.
11

SYNOPSIS

13           use Perl::Critic::TestUtils qw(critique pcritique fcritique);
14
15           my $code = '<<END_CODE';
16           package Foo::Bar;
17           $foo = frobulator();
18           $baz = $foo ** 2;
19           1;
20           END_CODE
21
22           # Critique code against all loaded policies...
23           my $perl_critic_config = { -severity => 2 };
24           my $violation_count = critique( \$code, $perl_critic_config);
25
26           # Critique code against one policy...
27           my $custom_policy = 'Miscellanea::ProhibitFrobulation'
28           my $violation_count = pcritique( $custom_policy, \$code );
29
30           # Critique code against one filename-related policy...
31           my $custom_policy = 'Modules::RequireFilenameMatchesPackage'
32           my $violation_count = fcritique( $custom_policy, \$code, 'Foo/Bar.pm' );
33

DESCRIPTION

35       This module is used by Perl::Critic only for self-testing. It provides
36       a few handy subroutines for testing new Perl::Critic::Policy modules.
37       Look at the test scripts that ship with Perl::Critic for more examples
38       of how to use these subroutines.
39

EXPORTS

41       block_perlcriticrc()
42           If a user has a ~/.perlcriticrc file, this can interfere with
43           testing.  This handy method disables the search for that file --
44           simply call it at the top of your .t program.  Note that this is
45           not easily reversible, but that should not matter.
46
47       critique_with_violations( $code_string_ref, $config_ref )
48           Test a block of code against the specified Perl::Critic::Config
49           instance (or "undef" for the default).  Returns the violations that
50           occurred.
51
52       critique( $code_string_ref, $config_ref )
53           Test a block of code against the specified Perl::Critic::Config
54           instance (or "undef" for the default).  Returns the number of
55           violations that occurred.
56
57       pcritique_with_violations( $policy_name, $code_string_ref, $config_ref
58       )
59           Like "critique_with_violations()", but tests only a single policy
60           instead of the whole bunch.
61
62       pcritique( $policy_name, $code_string_ref, $config_ref )
63           Like "critique()", but tests only a single policy instead of the
64           whole bunch.
65
66       fcritique_with_violations( $policy_name, $code_string_ref, $filename,
67       $config_ref )
68           Like "pcritique_with_violations()", but pretends that the code was
69           loaded from the specified filename.  This is handy for testing
70           policies like "Modules::RequireFilenameMatchesPackage" which care
71           about the filename that the source derived from.
72
73           The $filename parameter must be a relative path, not absolute.  The
74           file and all necessary subdirectories will be created via
75           File::Temp and will be automatically deleted.
76
77       fcritique( $policy_name, $code_string_ref, $filename, $config_ref )
78           Like "pcritique()", but pretends that the code was loaded from the
79           specified filename.  This is handy for testing policies like
80           "Modules::RequireFilenameMatchesPackage" which care about the
81           filename that the source derived from.
82
83           The $filename parameter must be a relative path, not absolute.  The
84           file and all necessary subdirectories will be created via
85           File::Temp and will be automatically deleted.
86
87       subtests_in_tree( $dir )
88           Searches the specified directory recursively for .run files.  Each
89           one found is parsed and a hash-of-list-of-hashes is returned.  The
90           outer hash is keyed on policy short name, like
91           "Modules::RequireEndWithOne".  The inner hash specifies a single
92           test to be handed to "pcritique()" or "fcritique()", including the
93           code string, test name, etc.  See below for the syntax of the .run
94           files.
95
96       should_skip_author_tests()
97           Answers whether author tests should run.
98
99       get_author_test_skip_message()
100           Returns a string containing the message that should be emitted when
101           a test is skipped due to it being an author test when author tests
102           are not enabled.
103
104       starting_points_including_examples()
105           Returns a list of the directories contain code that needs to be
106           tested when it is desired that the examples be included.
107
108       bundled_policy_names()
109           Returns a list of Policy packages that come bundled with this
110           package.  This functions by searching MANIFEST for
111           lib/Perl/Critic/Policy/*.pm and converts the results to package
112           names.
113
114       names_of_policies_willing_to_work( %configuration )
115           Returns a list of the packages of policies that are willing to
116           function on the current system using the specified configuration.
117

.run file information

119       Testing a policy follows a very simple pattern:
120
121           * Policy name
122               * Subtest name
123               * Optional parameters
124               * Number of failures expected
125               * Optional exception expected
126               * Optional filename for code
127
128       Each of the subtests for a policy is collected in a single .run file,
129       with test properties as comments in front of each code block that
130       describes how we expect Perl::Critic to react to the code.  For
131       example, say you have a policy called Variables::ProhibitVowels:
132
133           (In file t/Variables/ProhibitVowels.run)
134
135           ## name Basics
136           ## failures 1
137           ## cut
138
139           my $vrbl_nm = 'foo';    # Good, vowel-free name
140           my $wango = 12;         # Bad, pronouncable name
141
142
143           ## name Sometimes Y
144           ## failures 1
145           ## cut
146
147           my $yllw = 0;       # "y" not a vowel here
148           my $rhythm = 12;    # But here it is
149
150       These are called "subtests", and two are shown above.  The beauty of
151       incorporating multiple subtests in a file is that the .run is itself a
152       (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
153       color-coding still works, and it is much easier to work with the code
154       and the POD.
155
156       If you need to pass any configuration parameters for your subtest, do
157       so like this:
158
159           ## parms { allow_y => '0' }
160
161       Note that all the values in this hash must be strings because that's
162       what Perl::Critic will hand you from a .perlcriticrc.
163
164       If it's a TODO subtest (probably because of some weird corner of PPI
165       that we exercised that Adam is getting around to fixing, right?), then
166       make a "##TODO" entry.
167
168           ## TODO Should pass when PPI 1.xxx comes out
169
170       If the code is expected to trigger an exception in the policy, indicate
171       that like so:
172
173           ## error 1
174
175       If you want to test the error message, mark it with "/.../" to indicate
176       a "like()" test:
177
178           ## error /Can't load Foo::Bar/
179
180       If the policy you are testing cares about the filename of the code, you
181       can indicate that "fcritique" should be used like so (see "fcritique"
182       for more details):
183
184           ## filename lib/Foo/Bar.pm
185
186       The value of "parms" will get "eval"ed and passed to "pcritique()", so
187       be careful.
188
189       In general, a subtest document runs from the "## cut" that starts it to
190       either the next "## name" or the end of the file. In very rare
191       circumstances you may need to end the test document earlier. A second
192       "## cut" will do this. The only known need for this is in
193       t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the
194       RCS keywords in the file footer from producing false positives or
195       negatives in the last test.
196
197       Note that nowhere within the .run file itself do you specify the policy
198       that you're testing.  That's implicit within the filename.
199

BUGS AND CAVEATS AND TODO ITEMS

201       Test that we have a t/*/*.run for each lib/*/*.pm
202
203       Allow us to specify the nature of the failures, and which one.  If
204       there are 15 lines of code, and six of them fail, how do we know
205       they're the right six?
206

AUTHOR

208       Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.
209
211       Copyright (c) 2005-2009 Chris Dolan.
212
213       This program is free software; you can redistribute it and/or modify it
214       under the same terms as Perl itself.  The full text of this license can
215       be found in the LICENSE file included with this module.
216
217
218
219perl v5.12.1                      2010-09-08        Perl::Critic::TestUtils(3)
Impressum