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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::TestUtilUser Contributed Perl DocumentPerl::Critic::TestUtils(3)

NAME
       Perl::Critic::TestUtils - Utility functions for testing new Policies.

INTERFACE SUPPORT
       This is considered to be	a public module.  Any changes to its interface
       will go through a deprecation cycle.

SYNOPSIS
	   use Perl::Critic::TestUtils qw(critique pcritique fcritique);

	   my $code = '<<END_CODE';
	   package Foo::Bar;
	   $foo	= frobulator();
	   $baz	= $foo ** 2;
	   1;
	   END_CODE

	   # Critique code against all loaded policies...
	   my $perl_critic_config = { -severity	=> 2 };
	   my $violation_count = critique( \$code, $perl_critic_config);

	   # Critique code against one policy...
	   my $custom_policy = 'Miscellanea::ProhibitFrobulation'
	   my $violation_count = pcritique( $custom_policy, \$code );

	   # Critique code against one filename-related	policy...
	   my $custom_policy = 'Modules::RequireFilenameMatchesPackage'
	   my $violation_count = fcritique( $custom_policy, \$code, 'Foo/Bar.pm' );

DESCRIPTION
       This module is used by Perl::Critic only	for self-testing. It provides
       a few handy subroutines for testing new Perl::Critic::Policy modules.
       Look at the test	programs that ship with	Perl::Critic for more examples
       of how to use these subroutines.

EXPORTS
       assert_version( $version	)
	   Asserts that	the $version passed matches the	version	of
	   Perl::Critic.

       block_perlcriticrc()
	   If a	user has a ~/.perlcriticrc file, this can interfere with
	   testing.  This handy	method disables	the search for that file --
	   simply call it at the top of	your .t	program.  Note that this is
	   not easily reversible, but that should not matter.

       critique_with_violations( $code_string_ref, $config_ref )
	   Test	a block	of code	against	the specified Perl::Critic::Config
	   instance (or	"undef"	for the	default).  Returns the violations that
	   occurred.

       critique( $code_string_ref, $config_ref )
	   Test	a block	of code	against	the specified Perl::Critic::Config
	   instance (or	"undef"	for the	default).  Returns the number of
	   violations that occurred.

       pcritique_with_violations( $policy_name,	$code_string_ref, $config_ref
       )
	   Like	"critique_with_violations()", but tests	only a single policy
	   instead of the whole	bunch.

       pcritique( $policy_name,	$code_string_ref, $config_ref )
	   Like	"critique()", but tests	only a single policy instead of	the
	   whole bunch.

       fcritique_with_violations( $policy_name,	$code_string_ref, $filename,
       $config_ref )
	   Like	"pcritique_with_violations()", but pretends that the code was
	   loaded from the specified filename.	This is	handy for testing
	   policies like "Modules::RequireFilenameMatchesPackage" which	care
	   about the filename that the source derived from.

	   The $filename parameter must	be a relative path, not	absolute.  The
	   file	and all	necessary subdirectories will be created via
	   File::Temp and will be automatically	deleted.

       fcritique( $policy_name,	$code_string_ref, $filename, $config_ref )
	   Like	"pcritique()", but pretends that the code was loaded from the
	   specified filename.	This is	handy for testing policies like
	   "Modules::RequireFilenameMatchesPackage" which care about the
	   filename that the source derived from.

	   The $filename parameter must	be a relative path, not	absolute.  The
	   file	and all	necessary subdirectories will be created via
	   File::Temp and will be automatically	deleted.

       subtests_in_tree( $dir )
	   Searches the	specified directory recursively	for .run files.	 Each
	   one found is	parsed and a hash-of-list-of-hashes is returned.  The
	   outer hash is keyed on policy short name, like
	   "Modules::RequireEndWithOne".  The inner hash specifies a single
	   test	to be handed to	"pcritique()" or "fcritique()",	including the
	   code	string,	test name, etc.	 See below for the syntax of the .run
	   files.

       should_skip_author_tests()
	   Answers whether author tests	should run.

       get_author_test_skip_message()
	   Returns a string containing the message that	should be emitted when
	   a test is skipped due to it being an	author test when author	tests
	   are not enabled.

       starting_points_including_examples()
	   Returns a list of the directories contain code that needs to	be
	   tested when it is desired that the examples be included.

       bundled_policy_names()
	   Returns a list of Policy packages that come bundled with this
	   package.  This functions by searching MANIFEST for
	   lib/Perl/Critic/Policy/*.pm and converts the	results	to package
	   names.

       names_of_policies_willing_to_work( %configuration )
	   Returns a list of the packages of policies that are willing to
	   function on the current system using	the specified configuration.

.run file information
       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
       Test that we have a t/*/*.run for each lib/*/*.pm

       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?

AUTHOR
       Chris Dolan <cdolan@cpan.org> and the rest of the Perl::Critic team.

COPYRIGHT
       Copyright (c) 2005-2011 Chris Dolan.

       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	    Perl::Critic::TestUtils(3)

NAME | INTERFACE SUPPORT | SYNOPSIS | DESCRIPTION | EXPORTS | 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=Perl::Critic::TestUtils&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help