NAME

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

SYNOPSIS

           use Test::Perl::Critic::Policy qw< all_policies_ok >;

           # Assuming .run files are inside 't' directory...
           all_policies_ok()

           # Or if your .run files are in a different directory...
           all_policies_ok( '-test-directory' => 'run' );

           # And if you just want to run tests for some polices...
           all_policies_ok( -policies => ['Some::Policy', 'Another::Policy'] );

           # If you want your test program to accept short Policy names as
           # command-line parameters...
           #
           # You can then test a single policy by running
           # "perl -Ilib t/policy-test.t My::Policy".
           my %args = @ARGV ? ( -policies => [ @ARGV ] ) : ();
           all_policies_ok(%args);

DESCRIPTION

       This module provides a framework for function-testing your custom Perl::Critic::Policy modules.  Policy
       testing usually involves feeding it a string of Perl code and checking its behavior.  In the old days,
       those strings of Perl code were mixed directly in the test script.  That sucked.

IMPORTABLE SUBROUTINES

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

CREATING THE *.run FILES

       Testing a policy follows a very simple pattern:

           * Policy name
               * Subtest name
               * Optional parameters
               * Number of failures expected
               * Optional exception expected
               * Optional filename for code

       Each of the subtests for a policy is collected in a single .run file, with test properties as comments in
       front of each code block that describes how we expect Perl::Critic to react to the  code.   For  example,
       say you have a policy called Variables::ProhibitVowels:

           (In file t/Variables/ProhibitVowels.run)

           ## name Basics
           ## failures 1
           ## cut

           my $vrbl_nm = 'foo';    # Good, vowel-free name
           my $wango = 12;         # Bad, pronouncable name

           ## name Sometimes Y
           ## failures 1
           ## cut

           my $yllw = 0;       # "y" not a vowel here
           my $rhythm = 12;    # But here it is

       These are called "subtests", and two are shown above.  The beauty of incorporating multiple subtests in a
       file is that the .run is itself a (mostly) valid Perl file, and not hidden in a HEREDOC, so your editor's
       color-coding still works, and it is much easier to work with the code and the POD.

       If you need to pass any configuration parameters for your subtest, do so like this:

           ## parms { allow_y => '0' }

       Note that all the values in this hash must be strings because that's what Perl::Critic will hand you from
       a .perlcriticrc.

       If  it's  a  TODO  subtest  (probably  because of some weird corner of PPI that we exercised that Adam is
       getting around to fixing, right?), then make a "##TODO" entry.

           ## TODO Should pass when PPI 1.xxx comes out

       If the code is expected to trigger an exception in the policy, indicate that like so:

           ## error 1

       If you want to test the error message, mark it with "/.../" to indicate a "like()" test:

           ## error /Can't load Foo::Bar/

       If the policy you are testing cares about the filename of the code, you  can  indicate  that  "fcritique"
       should be used like so (see "fcritique" for more details):

           ## filename lib/Foo/Bar.pm

       The value of "parms" will get "eval"ed and passed to "pcritique()", so be careful.

       In  general, a subtest document runs from the "## cut" that starts it to either the next "## name" or the
       end of the file. In very rare circumstances you may need to end the test document earlier. A  second  "##
       cut"  will  do this. The only known need for this is in t/Miscellanea/RequireRcsKeywords.run, where it is
       used to prevent the RCS keywords in the file footer from producing false positives or  negatives  in  the
       last test.

       Note  that  nowhere  within  the  .run file itself do you specify the policy that you're testing.  That's
       implicit within the filename.

BUGS AND CAVEATS AND TODO ITEMS

       Add policy_ok() method for running subtests in just a single TODO file.

       Can users mark this entire test as TODO or SKIP, using the normal mechanisms?

       Allow us to specify the nature of the failures, and which one.  If there are 15 lines of code, and six of
       them fail, how do we know they're the right six?

       Consolidate code from Perl::Critic::TestUtils and possibly deprecate some functions there.

       Write unit tests for this module.

       Test that we have a t/*/*.run for each lib/*/*.pm

AUTHOR

       Andy Lester, Jeffrey Ryan Thalhammer <thaljef@cpan.org>

COPYRIGHT

       Copyright (c) 2009-2023 Andy Lester

       This program is free software; you can redistribute it and/or modify it under  the  same  terms  as  Perl
       itself.  The full text of this license can be found in the LICENSE file included with this module.

perl v5.36.0                                       2023-10-27                    Test::Perl::Critic::Policy(3pm)