1Test::Perl::Critic::PolUisceyr(3C)ontributed Perl DocumeTnetsatt:i:oPnerl::Critic::Policy(3)
2
3
4

NAME

6       Test::Perl::Critic::Policy - A framework for testing your custom
7       Policies
8

SYNOPSIS

10           use Test::Perl::Critic::Policy qw< all_policies_ok >;
11
12           # Assuming .run files are inside 't' directory...
13           all_policies_ok()
14
15           # Or if your .run files are in a different directory...
16           all_policies_ok( '-test-directory' => 'run' );
17
18           # And if you just want to run tests for some polices...
19           all_policies_ok( -policies => ['Some::Policy', 'Another::Policy'] );
20
21           # 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

DESCRIPTION

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
36       NOTE: This module is alpha code -- interfaces and implementation are
37       subject to major changes.  This module is an integral part of building
38       and testing Perl::Critic itself, but you should not write any code
39       against this module until it has stabilized.
40

IMPORTABLE SUBROUTINES

42       all_policies_ok('-test-directory' => $path, -policies =>
43       \@policy_names)
44           Loads all the *.run files beneath the "-test-directory" and runs
45           the tests.  If "-test-directory" is not specified, it defaults to
46           t/.  "-policies" is an optional reference to an array of shortened
47           Policy names.  If "-policies" specified, only the tests for
48           Policies that match one of the "m/$POLICY_NAME/imx" will be run.
49

CREATING THE *.run FILES

51       Testing a policy follows a very simple pattern:
52
53           * Policy name
54               * Subtest name
55               * Optional parameters
56               * Number of failures expected
57               * Optional exception expected
58               * Optional filename for code
59
60       Each of the subtests for a policy is collected in a single .run file,
61       with test properties as comments in front of each code block that
62       describes how we expect Perl::Critic to react to the code.  For
63       example, say you have a policy called Variables::ProhibitVowels:
64
65           (In file t/Variables/ProhibitVowels.run)
66
67           ## name Basics
68           ## failures 1
69           ## cut
70
71           my $vrbl_nm = 'foo';    # Good, vowel-free name
72           my $wango = 12;         # Bad, pronouncable name
73
74
75           ## name Sometimes Y
76           ## failures 1
77           ## cut
78
79           my $yllw = 0;       # "y" not a vowel here
80           my $rhythm = 12;    # But here it is
81
82       These are called "subtests", and two are shown above.  The beauty of
83       incorporating multiple subtests in a file is that the .run is itself a
84       (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
85       color-coding still works, and it is much easier to work with the code
86       and the POD.
87
88       If you need to pass any configuration parameters for your subtest, do
89       so like this:
90
91           ## parms { allow_y => '0' }
92
93       Note that all the values in this hash must be strings because that's
94       what Perl::Critic will hand you from a .perlcriticrc.
95
96       If it's a TODO subtest (probably because of some weird corner of PPI
97       that we exercised that Adam is getting around to fixing, right?), then
98       make a "##TODO" entry.
99
100           ## TODO Should pass when PPI 1.xxx comes out
101
102       If the code is expected to trigger an exception in the policy, indicate
103       that like so:
104
105           ## error 1
106
107       If you want to test the error message, mark it with "/.../" to indicate
108       a "like()" test:
109
110           ## error /Can't load Foo::Bar/
111
112       If the policy you are testing cares about the filename of the code, you
113       can indicate that "fcritique" should be used like so (see "fcritique"
114       for more details):
115
116           ## filename lib/Foo/Bar.pm
117
118       The value of "parms" will get "eval"ed and passed to "pcritique()", so
119       be careful.
120
121       In general, a subtest document runs from the "## cut" that starts it to
122       either the next "## name" or the end of the file. In very rare
123       circumstances you may need to end the test document earlier. A second
124       "## cut" will do this. The only known need for this is in
125       t/Miscellanea/RequireRcsKeywords.run, where it is used to prevent the
126       RCS keywords in the file footer from producing false positives or
127       negatives in the last test.
128
129       Note that nowhere within the .run file itself do you specify the policy
130       that you're testing.  That's implicit within the filename.
131

BUGS AND CAVEATS AND TODO ITEMS

133       Add policy_ok() method for running subtests in just a single TODO file.
134
135       Can users mark this entire test as TODO or SKIP, using the normal
136       mechanisms?
137
138       Allow us to specify the nature of the failures, and which one.  If
139       there are 15 lines of code, and six of them fail, how do we know
140       they're the right six?
141
142       Consolidate code from Perl::Critic::TestUtils and possibly deprecate
143       some functions there.
144
145       Write unit tests for this module.
146
147       Test that we have a t/*/*.run for each lib/*/*.pm
148

AUTHOR

150       Andy Lester, Jeffrey Ryan Thalhammer <thaljef@cpan.org>
151
153       Copyright (c) 2009-2011 Andy Lester
154
155       This program is free software; you can redistribute it and/or modify it
156       under the same terms as Perl itself.  The full text of this license can
157       be found in the LICENSE file included with this module.
158
159
160
161perl v5.32.0                      2020-07-28     Test::Perl::Critic::Policy(3)
Impressum