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 programs that ship with Perl::Critic for more examples
38       of how to use these subroutines.
39

EXPORTS

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

.run file information

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

BUGS AND CAVEATS AND TODO ITEMS

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

AUTHOR

212       Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.
213
215       Copyright (c) 2005-2011 Chris Dolan.
216
217       This program is free software; you can redistribute it and/or modify it
218       under the same terms as Perl itself.  The full text of this license can
219       be found in the LICENSE file included with this module.
220
221
222
223perl v5.28.1                      2019-02-02        Perl::Critic::TestUtils(3)
Impressum