Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Test::Perl::Critic::PoUser(Contributed Perl DocumTest::Perl::Critic::Policy(3)

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.

       NOTE: This module is alpha code -- interfaces and implementation	are
       subject to major	changes.  This module is an integral part of building
       and testing Perl::Critic	itself,	but you	should not write any code
       against this module until it has	stabilized.

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-2011 Andy Lester.  All rights	reserved.

       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.24.1			  2017-07-02	 Test::Perl::Critic::Policy(3)

NAME | SYNOPSIS | DESCRIPTION | IMPORTABLE SUBROUTINES | CREATING THE *.run FILES | BUGS AND CAVEATS AND TODO ITEMS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Test::Perl::Critic::Policy&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help