1Test::Perl::Critic::PolUisceyr(3C)ontributed Perl DocumeTnetsatt:i:oPnerl::Critic::Policy(3)
2
6 Test::Perl::Critic::Policy - A framework for testing your custom
7 Policies
8
10 use Test::Perl::Critic::Policy qw< all_policies_ok >;
11 # Assuming .run files are inside 't' directory...
13 all_policies_ok()
14 # Or if your .run files are in a different directory...
16 all_policies_ok( '-test-directory' => 'run' );
17 # And if you just want to run tests for some polices...
19 all_policies_ok( -policies => ['Some::Policy', 'Another::Policy'] );
20 # If you want your test program to accept short Policy names as
22 # command-line parameters...
23 #
24 # You can then test a single policy by running
25 # "perl -Ilib t/policy-test.t My::Policy".
26 my %args = @ARGV ? ( -policies => [ @ARGV ] ) : ();
27 all_policies_ok(%args);
28
30 This module provides a framework for function-testing your custom
31 Perl::Critic::Policy modules. Policy testing usually involves feeding
32 it a string of Perl code and checking its behavior. In the old days,
33 those strings of Perl code were mixed directly in the test script.
34 That sucked.
35
37 all_policies_ok('-test-directory' => $path, -policies =>
38 \@policy_names)
39 Loads all the *.run files beneath the "-test-directory" and runs
40 the tests. If "-test-directory" is not specified, it defaults to
41 t/. "-policies" is an optional reference to an array of shortened
42 Policy names. If "-policies" specified, only the tests for
43 Policies that match one of the "m/$POLICY_NAME/imx" will be run.
44
46 Testing a policy follows a very simple pattern:
47 * Policy name
49 * Subtest name
50 * Optional parameters
51 * Number of failures expected
52 * Optional exception expected
53 * Optional filename for code
54 Each of the subtests for a policy is collected in a single .run file,
56 with test properties as comments in front of each code block that
57 describes how we expect Perl::Critic to react to the code. For
58 example, say you have a policy called Variables::ProhibitVowels:
59 (In file t/Variables/ProhibitVowels.run)
61 ## name Basics
63 ## failures 1
64 ## cut
65 my $vrbl_nm = 'foo'; # Good, vowel-free name
67 my $wango = 12; # Bad, pronouncable name
68 ## name Sometimes Y
71 ## failures 1
72 ## cut
73 my $yllw = 0; # "y" not a vowel here
75 my $rhythm = 12; # But here it is
76 These are called "subtests", and two are shown above. The beauty of
78 incorporating multiple subtests in a file is that the .run is itself a
79 (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
80 color-coding still works, and it is much easier to work with the code
81 and the POD.
82 If you need to pass any configuration parameters for your subtest, do
84 so like this:
85 ## parms { allow_y => '0' }
87 Note that all the values in this hash must be strings because that's
89 what Perl::Critic will hand you from a .perlcriticrc.
90 If it's a TODO subtest (probably because of some weird corner of PPI
92 that we exercised that Adam is getting around to fixing, right?), then
93 make a "##TODO" entry.
94 ## TODO Should pass when PPI 1.xxx comes out
96 If the code is expected to trigger an exception in the policy, indicate
98 that like so:
99 ## error 1
101 If you want to test the error message, mark it with "/.../" to indicate
103 a like() test:
104 ## error /Can't load Foo::Bar/
106 If the policy you are testing cares about the filename of the code, you
108 can indicate that "fcritique" should be used like so (see "fcritique"
109 for more details):
110 ## filename lib/Foo/Bar.pm
112 The value of "parms" will get "eval"ed and passed to pcritique(), so be
114 careful.
115 In general, a subtest document runs from the "## cut" that starts it to
117 either the next "## name" or the end of the file. In very rare
118 circumstances you may need to end the test document earlier. A second
119 "## cut" will do this. The only known need for this is in
120 t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the
121 RCS keywords in the file footer from producing false positives or
122 negatives in the last test.
123 Note that nowhere within the .run file itself do you specify the policy
125 that you're testing. That's implicit within the filename.
126
128 Add policy_ok() method for running subtests in just a single TODO file.
129 Can users mark this entire test as TODO or SKIP, using the normal
131 mechanisms?
132 Allow us to specify the nature of the failures, and which one. If
134 there are 15 lines of code, and six of them fail, how do we know
135 they're the right six?
136 Consolidate code from Perl::Critic::TestUtils and possibly deprecate
138 some functions there.
139 Write unit tests for this module.
141 Test that we have a t/*/*.run for each lib/*/*.pm
143
145 Andy Lester, Jeffrey Ryan Thalhammer <thaljef@cpan.org>
146
148 Copyright (c) 2009-2023 Andy Lester
149 This program is free software; you can redistribute it and/or modify it
151 under the same terms as Perl itself. The full text of this license can
152 be found in the LICENSE file included with this module.
153perl v5.36.0 2023-03-05 Test::Perl::Critic::Policy(3)