1Perl::Critic::TestUtilsU(s3e)r Contributed Perl DocumentaPteiroln::Critic::TestUtils(3)
2
6 Perl::Critic::TestUtils - Utility functions for testing new Policies
7
9 use Perl::Critic::TestUtils qw(critique pcritique fcritique);
10 my $code = '<<END_CODE';
12 package Foo::Bar;
13 $foo = frobulator();
14 $baz = $foo ** 2;
15 1;
16 END_CODE
17 # Critique code against all loaded policies...
19 my $perl_critic_config = { -severity => 2 };
20 my $violation_count = critique( \$code, $perl_critic_config);
21 # Critique code against one policy...
23 my $custom_policy = 'Miscellanea::ProhibitFrobulation'
24 my $violation_count = pcritique( $custom_policy, \$code );
25 # Critique code against one filename-related policy...
27 my $custom_policy = 'Modules::RequireFilenameMatchesPackage'
28 my $violation_count = fcritique( $custom_policy, \$code, 'Foo/Bar.pm' );
29
31 This module is used by Perl::Critic only for self-testing. It provides
32 a few handy subroutines for testing new Perl::Critic::Policy modules.
33 Look at the test scripts that ship with Perl::Critic for more examples
34 of how to use these subroutines.
35
37 block_perlcriticrc()
38 If a user has a ~/.perlcriticrc file, this can interfere with test‐
39 ing. This handy method disables the search for that file -- simply
40 call it at the top of your .t program. Note that this is not eas‐
41 ily reversible, but that should not matter.
42 critique( $code_string_ref, $config_ref )
44 Test a block of code against the specified Perl::Critic::Config
45 instance (or "undef" for the default). Returns the number of vio‐
46 lations that occurred
47 pcritique( $policy_name, $code_string_ref, $config_ref )
49 Like "critique()", but tests only a single policy instead of the
50 whole bunch.
51 fcritique( $policy_name, $code_string_ref, $filename, $config_ref )
53 Like "pcritique()", but pretends that the code was loaded from the
54 specified filename. This is handy for testing policies like "Mod‐
55 ules::RequireFilenameMatchesPackage" which care about the filename
56 that the source derived from.
57 The $filename parameter must be a relative path, not absolute. The
59 file and all necessary subdirectories will be created via
60 File::Temp and will be automatically deleted.
61 subtests_in_tree( $dir )
63 Searches the specified directory recursively for .run files. Each
64 one found is parsed and a hash-of-list-of-hashes is returned. The
65 outer hash is keyed on policy short name, like "Mod‐
66 ules::RequireEndWithOne". The inner hash specifies a single test
67 to be handed to "pcritique()" or "fcritique()", including the code
68 string, test name, etc. See below for the syntax of the .run
69 files.
70 should_skip_author_tests()
72 Answers whether author tests should run.
73 get_author_test_skip_message()
75 Returns a string containing the message that should be emitted when
76 a test is skipped due to it being an author test when author tests
77 are not enabled.
78 starting_points_including_examples()
80 Returns a list of the directories contain code that needs to be
81 tested when it is desired that the examples be included.
82 bundled_policy_names()
84 Returns a list of Policy packages that come bundled with this pack‐
85 age. This functions by searching MANIFEST for lib/Perl/Critic/Pol‐
86 icy/*.pm and converts the results to package names.
87
89 Testing a policy follows a very simple pattern:
90 * Policy name
92 * Subtest name
93 * Optional parameters
94 * Number of failures expected
95 * Optional exception expected
96 * Optional filename for code
97 Each of the subtests for a policy is collected in a single .run file,
99 with test properties as comments in front of each code block that
100 describes how we expect Perl::Critic to react to the code. For exam‐
101 ple, say you have a policy called Variables::ProhibitVowels:
102 (In file t/Variables/ProhibitVowels.run)
104 ## name Basics
106 ## failures 1
107 ## cut
108 my $vrbl_nm = 'foo'; # Good, vowel-free name
110 my $wango = 12; # Bad, pronouncable name
111 ## name Sometimes Y
113 ## failures 1
114 ## cut
115 my $yllw = 0; # "y" not a vowel here
117 my $rhythm = 12; # But here it is
118 These are called "subtests", and two are shown above. The beauty of
120 incorporating multiple subtests in a file is that the .run is itself a
121 (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
122 color-coding still works, and it is much easier to work with the code
123 and the POD.
124 If you need to pass any configuration parameters for your subtest, do
126 so like this:
127 ## parms { allow_y => 0 }
129 If it's a TODO subtest (probably because of some weird corner of PPI
131 that we exercised that Adam is getting around to fixing, right?), then
132 make a "##TODO" entry.
133 ## TODO Should pass when PPI 1.xxx comes out
135 If the code is expected to trigger an exception in the policy, indicate
137 that like so:
138 ## error 1
140 If you want to test the error message, mark it with "/.../" to indicate
142 a "like()" test:
143 ## error /Can't load Foo::Bar/
145 If the policy you are testing cares about the filename of the code, you
147 can indicate that "fcritique" should be used like so (see "fcritique"
148 for more details):
149 ## filename lib/Foo/Bar.pm
151 The value of "parms" will get "eval"ed and passed to "pcritique()", so
153 be careful.
154 Note that nowhere within the .run file itself do you specify the policy
156 that you're testing. That's implicit within the filename.
157
159 Test that we have a t/*/*.run for each lib/*/*.pm
160 Allow us to specify the nature of the failures, and which one. If
162 there are 15 lines of code, and six of them fail, how do we know
163 they're the right six?
164
166 Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.
167
169 Copyright (c) 2005-2007 Chris Dolan. All rights reserved.
170 This program is free software; you can redistribute it and/or modify it
172 under the same terms as Perl itself. The full text of this license can
173 be found in the LICENSE file included with this module.
174perl v5.8.8 2007-03-20 Perl::Critic::TestUtils(3)